# ═══════════════════════════════════════════════════════════════════════════════
# L1JTW380 環境變數設定指南
# 2026-01-19 Config: 說明如何使用環境變數管理配置
# ═══════════════════════════════════════════════════════════════════════════════
## 目錄
1. [簡介](#1-簡介)
2. [環境變數列表](#2-環境變數列表)
3. [設定方法](#3-設定方法)
4. [安全性](#4-安全性)
5. [範例](#5-範例)
---
## 1. 簡介
### 為什麼使用環境變數？
- **安全性**：敏感資訊 (密碼) 不會寫入程式碼或配置檔案
- **靈活性**：不同環境 (開發/測試/生產) 使用不同設定
- **便捷性**：無需修改程式碼即可變更設定
- **標準化**：符合 12-Factor App 設計原則
### ConfigManager 支援
`ConfigManager` 會自動將 `L1JTW_*` 開頭的環境變數對應到配置：
```java
// 環境變數
L1JTW_DB_URL=jdbc:mysql://prod-db/380
// 程式碼取得
String url = ConfigManager.getInstance().get("db.url", String.class);
// 結果: "jdbc:mysql://prod-db/380"
```
---
## 2. 環境變數列表
### 2.1 資料庫相關
| 環境變數 | 配置鍵 | 預設值 | 說明 |
|----------|--------|--------|------|
| `L1JTW_DB_URL` | `db.url` | `jdbc:mysql://localhost/380` | 資料庫連線 URL |
| `L1JTW_DB_USERNAME` | `db.username` | `root` | 資料庫使用者名稱 |
| `L1JTW_DB_PASSWORD` | `db.password` | `root` | 資料庫密碼 (敏感) |
| `L1JTW_DB_DRIVER` | `db.driver` | `com.mysql.cj.jdbc.Driver` | JDBC 驅動 |
| `L1JTW_DB_MIN_IDLE` | `db.min-idle` | `60` | 最小空閒連接數 |
| `L1JTW_DB_MAX_POOL_SIZE` | `db.max-pool-size` | `500` | 最大連接池大小 |
| `L1JTW_DB_CONNECTION_TIMEOUT` | `db.connection-timeout` | `10000` | 連接超時 (ms) |
| `L1JTW_DB_IDLE_TIMEOUT` | `db.idle-timeout` | `300000` | 空閒超時 (ms) |
| `L1JTW_DB_MAX_LIFETIME` | `db.max-lifetime` | `900000` | 連接生命週期 (ms) |
### 2.2 伺服器相關
| 環境變數 | 配置鍵 | 預設值 | 說明 |
|----------|--------|--------|------|
| `L1JTW_SERVER_HOSTNAME` | `server.hostname` | `*` | 伺服器主機名稱 |
| `L1JTW_SERVER_PORT` | `server.port` | `2000` | 伺服器連接埠 |
| `L1JTW_SERVER_MAX_USERS` | `server.max-users` | `500` | 最大線上人數 |
| `L1JTW_SERVER_TIMEZONE` | `server.timezone` | `Asia/Taipei` | 時區設定 |
### 2.3 快取相關
| 環境變數 | 配置鍵 | 預設值 | 說明 |
|----------|--------|--------|------|
| `L1JTW_CACHE_ENABLED` | `cache.enabled` | `true` | 是否啟用快取 |
| `L1JTW_CACHE_HOT_DATA_TTL` | `cache.hot-data-ttl` | `1800` | 熱資料 TTL (秒) |
| `L1JTW_CACHE_QUERY_TTL` | `cache.query-ttl` | `300` | 查詢快取 TTL (秒) |
| `L1JTW_CACHE_MAX_SIZE` | `cache.max-size` | `10000` | 快取最大大小 |
### 2.4 監控相關
| 環境變數 | 配置鍵 | 預設值 | 說明 |
|----------|--------|--------|------|
| `L1JTW_MONITOR_ENABLED` | `monitor.enabled` | `true` | 是否啟用監控 |
| `L1JTW_MONITOR_SLOW_QUERY` | `monitor.slow-query-threshold` | `1000` | 慢查詢閾值 (ms) |
---
## 3. 設定方法
### 3.1 Linux / macOS
#### 臨時設定 (當前終端機有效)
```bash
export L1JTW_DB_PASSWORD="your_password"
export L1JTW_SERVER_MAX_USERS=500
export L1JTW_CACHE_ENABLED=true
```
#### 永久設定 (使用者層級)
```bash
# 編輯 ~/.bashrc 或 ~/.bash_profile
nano ~/.bashrc
# 加入以下內容
export L1JTW_DB_URL="jdbc:mysql://prod-db/380"
export L1JTW_DB_USERNAME="l1jtw_user"
export L1JTW_DB_PASSWORD="your_secure_password"
export L1JTW_SERVER_MAX_USERS=500
# 重新載入
source ~/.bashrc
```
#### 永久設定 (系統層級)
```bash
# 編輯 /etc/environment
sudo nano /etc/environment
# 加入以下內容
L1JTW_DB_URL="jdbc:mysql://prod-db/380"
L1JTW_DB_USERNAME="l1jtw_user"
L1JTW_DB_PASSWORD="your_secure_password"
```
### 3.2 Windows
#### 臨時設定 (當前 CMD 有效)
```cmd
set L1JTW_DB_PASSWORD=your_password
set L1JTW_SERVER_MAX_USERS=500
```
#### 永久設定
```cmd
# 開啟系統屬性 > 環境變數
# 新增使用者變數或系統變數
```
#### PowerShell
```powershell
$env
1JTW_DB_PASSWORD = "your_password"
$env
1JTW_SERVER_MAX_USERS = "500"
```
### 3.3 Docker / Docker Compose
#### Dockerfile
```dockerfile
ENV L1JTW_DB_URL=jdbc:mysql://prod-db/380
ENV L1JTW_DB_USERNAME=l1jtw_user
ENV L1JTW_DB_PASSWORD=your_secure_password
ENV L1JTW_SERVER_MAX_USERS=500
```
#### docker-compose.yml
```yaml
version: '3.8'
services:
l1jtw-server:
image: l1jtw380:latest
environment:
- L1JTW_DB_URL=jdbc:mysql://mysql-server/380
- L1JTW_DB_USERNAME=l1jtw_user
- L1JTW_DB_PASSWORD=${DB_PASSWORD}
- L1JTW_SERVER_MAX_USERS=500
- L1JTW_CACHE_ENABLED=true
secrets:
- db_password
```
---
## 4. 安全性
### 4.1 敏感資訊處理
**⚠️ 重要提醒**
1. **永遠不要**將密碼寫入配置檔案或程式碼
2. **永遠不要**將敏感資訊提交到版本控制系統
3. **使用**環境變數或秘密管理工具
### 4.2 秘密管理工具
#### 使用 Docker Secrets
```yaml
secrets:
db_password:
file: ./secrets/db_password.txt
```
#### 使用 HashiCorp Vault
```bash
# 取得秘密
vault kv get secret/l1jtw/database
# 環境變數注入
export L1JTW_DB_PASSWORD=$(vault kv get -field=password secret/l1jtw/database)
```
#### 使用 AWS Secrets Manager
```bash
# 取得秘密
aws secretsmanager get-secret-value --secret-id l1jtw/db
# 解析 JSON 並設定環境變數
export L1JTW_DB_PASSWORD=$(aws secretsmanager get-secret-value --secret-id l1jtw/db --query SecretString --output text | jq -r '.password')
```
### 4.3 .env 檔案 (開發環境)
建立 `.env` 檔案：
```bash
# .env - 此檔案不應提交到版本控制
L1JTW_DB_URL=jdbc:mysql://localhost/380
L1JTW_DB_USERNAME=root
L1JTW_DB_PASSWORD=your_development_password
L1JTW_SERVER_MAX_USERS=500
```
在 `.gitignore` 中加入：
```
.env
*.pem
*.key
secrets/
```
---
## 5. 範例
### 5.1 開發環境
```bash
export L1JTW_DB_URL="jdbc:mysql://localhost/380"
export L1JTW_DB_USERNAME="root"
export L1JTW_DB_PASSWORD="dev_password"
export L1JTW_SERVER_MAX_USERS=100
export L1JTW_CACHE_ENABLED=true
export L1JTW_CACHE_QUERY_TTL=60
```
### 5.2 測試環境
```bash
export L1JTW_DB_URL="jdbc:mysql://test-db.example.com/380"
export L1JTW_DB_USERNAME="l1jtw_test"
export L1JTW_DB_PASSWORD="${TEST_DB_PASSWORD}"
export L1JTW_SERVER_MAX_USERS=200
export L1JTW_CACHE_ENABLED=true
export L1JTW_CACHE_QUERY_TTL=300
```
### 5.3 生產環境
```bash
export L1JTW_DB_URL="jdbc:mysql://prod-db.example.com/380?useSSL=true&requireSSL=true"
export L1JTW_DB_USERNAME="l1jtw_prod"
export L1JTW_DB_PASSWORD="${PROD_DB_PASSWORD}"
export L1JTW_SERVER_MAX_USERS=500
export L1JTW_CACHE_ENABLED=true
export L1JTW_CACHE_HOT_DATA_TTL=3600
export L1JTW_CACHE_QUERY_TTL=600
export L1JTW_MONITOR_ENABLED=true
export L1JTW_MONITOR_SLOW_QUERY=500
```
### 5.4 systemd 服務
建立 `/etc/systemd/system/l1jtw.service`：
```ini
[Unit]
Description=L1JTW380 Game Server
After=network.target mysql.service
[Service]
Type=simple
User=l1jtw
Group=l1jtw
WorkingDirectory=/opt/l1jtw380
ExecStart=/usr/bin/java -jar l1jserver.jar
# 環境變數
Environment="L1JTW_DB_URL=jdbc:mysql://localhost/380"
Environment="L1JTW_DB_USERNAME=l1jtw"
Environment="L1JTW_DB_PASSWORD=${DB_PASSWORD}"
Environment="L1JTW_SERVER_MAX_USERS=500"
Environment="L1JTW_CACHE_ENABLED=true"
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
```
---
## 6. 故障排除
### 環境變數未生效
1. 確認環境變數名稱前綴為 `L1JTW_`
2. 確認環境變數已匯出 (`export`)
3. 確認程式碼中使用 `ConfigManager.getInstance().get()` 取得值
4. 檢查日誌是否有 `[ConfigManager]` 相關訊息
### 優先順序
ConfigManager 的配置載入優先順序：
1. 環境變數 (最高優先)
2. 命令列參數
3. 配置文件
4. 預設值 (最低優先)
---
## 相關文件
- [CHANGELOG.md](docs/CHANGELOG.md)
- [OPTIMIZATION_PLAN.md](docs/OPTIMIZATION_PLAN.md)
- [database.properties.example](config/database.properties.example)
雷達卡
發表於 2026-2-17 19:12
提升卡
置頂卡
變色卡
千斤頂
