跳轉到

環境變數與營運

這一頁整理的是：

  • 目前程式實際依賴哪些 env
  • 哪些設定會影響執行結果
  • 營運與排錯時該注意什麼

一、核心環境變數

1. SHIOAJI_API_KEY

用途：

  • ShioajiQuote 登入用

2. SHIOAJI_SECRET_KEY

用途：

  • ShioajiQuote 登入用

3. DB_TYPE

用途：

  • 決定資料庫型態

可選值：

  • sqlite
  • postgresql

4. SQLITE_PATH

用途：

  • SQLite 檔案路徑

5. DATABASE_URL

用途：

  • PostgreSQL 連線字串

6. STRATEGY_NAME

用途：

  • 啟動時 current_strategy_name 的初始值

注意：

  • 只是初始值
  • 後續可被 POST /set_strategy 改掉
  • 若不在可見策略清單中，會被 fallback

7. OPTIMIZATION_WORKERS

用途：

  • 控制最佳化任務多進程數量

若未設：

  • 會 fallback 成 os.cpu_count() - 1

二、建議的 .env.example

雖然目前 repo 內不一定完整提供，但若你要正式化，建議整理成：

# quote providers
SHIOAJI_API_KEY=
SHIOAJI_SECRET_KEY=

# database
DB_TYPE=sqlite
SQLITE_PATH=./training_params.db
# DATABASE_URL=postgresql+psycopg2://USER:PASSWORD@HOST:PORT/DBNAME

# runtime
STRATEGY_NAME=BollingerATRStrategy
OPTIMIZATION_WORKERS=4

三、啟動時的真實行為

這個專案的啟動，不只是開一個 API server。

app.py 載入時會：

  1. load_dotenv()
  2. 初始化 ShioajiQuote()
  3. 初始化 DataBentoQuote()
  4. 建立 DB
  5. 印 startup config
  6. 直接跑一次 run_backtest(...)

這代表：

  • 啟動可能需要外部 API 可用
  • 啟動可能需要金鑰正確
  • 啟動速度不只是 web server 起來而已

四、營運風險

1. 啟動有副作用

風險：

  • 健康檢查延遲
  • restart 成本高
  • 外部資料源一掛，服務可能啟不來

2. 本地檔持久化

目前除了 DB，還有：

  • backtest_history.json
  • 某些舊腳本會寫 state.json

風險：

  • 多實例不一致
  • 重啟後狀態不一致
  • 容器化時容易出問題

3. 外部金鑰與資料依賴

系統不是純離線回測器，它依賴：

  • shioaji
  • databento
  • 部分舊腳本的 polygon

所以營運時必須釐清：

  • 哪些功能需要外部行情
  • 哪些功能可只用既有快取或 DB

五、最佳化任務的營運注意事項

最佳化會吃：

  • CPU
  • RAM
  • 資料載入時間

相關變數：

  • OPTIMIZATION_WORKERS

建議：

  • 小主機不要開太高
  • 若與 API 共機，避免把機器打滿

六、策略與營運的關係

雖然可透過 API 切策略，但營運層面要理解：

  • .env 的 STRATEGY_NAME 只是初始值
  • 真正運行中依賴的是 current_strategy_name
  • 而且受可見策略清單影響

因此排錯時，要先看：

  1. .env 想設定什麼
  2. strategy_registry.py 是否允許這個策略
  3. 當前 API 狀態下 GET /get_strategy 是什麼

七、建議的營運檢查清單

每次部署或重啟前，至少確認：

  1. .env 是否完整
  2. 資料庫是否可連
  3. SHIOAJI_* 是否正確
  4. 啟動後 GET /strategy_list 是否正常
  5. GET /get_strategy 是否符合預期
  6. GET /get_params 是否可正常回應
  7. GET /state 是否可取回 state
  8. GET /optimization/tasks 是否正常

八、排錯順序建議

啟動失敗

先查：

  1. env
  2. quote adapter 初始化
  3. DB migration
  4. 啟動時初始回測

一般回測結果怪怪的

先查：

  1. GET /get_strategy
  2. GET /get_params
  3. GET /get_timeframe
  4. GET /get_time_range
  5. GET /state?strategy_name=... 是否與預期一致

最佳化跑很慢

先查：

  1. OPTIMIZATION_WORKERS
  2. 組合數量是否過大
  3. 前端是否誤用完整結果端點輪詢

九、若要正式化營運

建議未來補：

  • .env.example
  • Dockerfile
  • docker-compose.yml
  • health check endpoint
  • 結構化 logging
  • background worker 架構