開發環境設定¶

啟動時間

Clone、安裝相依套件、docker compose up -d — API 在 5 分鐘內可於 localhost:9879 使用。資料庫（RDS）和 Redis（ElastiCache）預設連接 AWS 受管理服務；透過 .env 覆寫可使用本地執行個體進行完全離線開發。

前置需求¶

工具	版本	用途
Python	3.11+	API + Worker 執行環境
Node.js	20+	前端建構
Docker	24+	容器建構
Docker Compose	v2+	本機開發
AWS CLI	v2	Secrets Manager 存取

快速開始¶

1. 複製並安裝¶

git clone git@github.com:fullpass-4pass/4pass.git
cd 4pass

# Python dependencies
pip install -r requirements.txt

# Frontend dependencies
cd frontend && npm install && cd ..

2. Docker Compose（建議方式）¶

# Build API image (includes frontend)
docker compose build

# Build worker image (separate optimized build)
docker compose build worker-image

# Start services
docker compose up -d

定義的服務¶

服務	連接埠	說明
`api`	9879:8000	FastAPI + Vue.js SPA
`worker-image`	—	僅建構用（Worker Docker 映像）

Note

資料庫（RDS）和 Redis（ElastiCache）即使在開發環境也作為 AWS 託管服務運行。透過環境變數或 .env 檔案進行設定。

3. 初始化資料庫¶

curl -X POST "http://localhost:9879/setup/fresh-start" \
  -H "Authorization: Bearer $SETUP_API_KEY"

環境變數¶

核心¶

變數	說明	範例
`DATABASE_URL`	PostgreSQL 連線字串	`postgresql://user:pass@host:5432/db`
`REDIS_URL`	Redis/Valkey 連線字串	`redis://host:6379/0`
`JWT_SECRET_KEY`	JWT 簽章金鑰	`secrets.token_urlsafe(32)`
`SETUP_API_KEY`	資料庫初始化金鑰	隨機字串

加密¶

變數	說明	範例
`ENCRYPTION_KEY`	主加密金鑰（本機模式）	`secrets.token_urlsafe(32)`
`USE_AWS_KMS`	啟用 KMS 加密	`true` / `false`
`FRONTEND_KMS_KEY_ID`	前端加密 KMS 金鑰別名	`alias/frontend-encryption`

ECS（正式環境）¶

變數	說明	範例
`ECS_CLUSTER`	ECS 叢集名稱	`shioaji-cluster`
`ECS_TASK_DEFINITION`	Worker 任務定義	`shioaji-worker`
`ECS_SUBNETS`	逗號分隔的子網路 ID	`subnet-xxx,subnet-yyy`
`ECS_SECURITY_GROUPS`	Worker 安全群組	`sg-xxx`
`ECS_LAUNCH_TYPE`	EC2 或 FARGATE	`EC2`
`WORKER_IDLE_TIMEOUT`	Worker 閒置逾時（秒）	`1800`（30 分鐘）

選用¶

變數	說明	預設值
`CAPTCHA_ENABLED`	啟用 Cloudflare Turnstile	`false`
`CAPTCHA_SECRET_KEY`	Turnstile 秘密金鑰	—
`ORDER_TASK_QUEUE_URL`	下單任務 SQS 佇列	—（退回至 BackgroundTasks）
`WORKER_CONTROL_QUEUE_URL`	Worker 控制 SQS FIFO	—

專案結構¶

├── app/                         # FastAPI application
│   ├── main.py                  # Entry point, middleware stack
│   ├── core/                    # Auth, crypto, database, Redis
│   ├── models/                  # SQLAlchemy models
│   ├── routers/                 # API endpoints
│   ├── schemas/                 # Pydantic models
│   ├── services/                # Business logic + brokers
│   └── alembic/                 # Database migrations
├── lambda/                      # Lambda functions (5 handlers)
├── backtest/                    # PineScript compiler + backtester
├── frontend/                    # Vue 3 SPA
├── terraform/                   # AWS IaC (~80 resources)
├── scripts/                     # Build scripts (Lambda layer, etc.)
├── docs/                        # This documentation site
├── Dockerfile                   # API multi-stage build
├── Dockerfile.worker            # Worker optimized build (254 MB)
├── docker-compose.yaml          # Local development
├── requirements.txt             # API dependencies
├── requirements-worker.txt      # Worker dependencies
└── mkdocs.yml                   # Documentation config

資料庫遷移¶

# Create a new migration
cd app && alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback one step
alembic downgrade -1

執行回測引擎¶

# Run a strategy
python -m backtest --script backtest/strategies/macd_crossover.pine --timeframe 4h

# Without magnifier (faster, less realistic)
python -m backtest --script backtest/strategies/supertrend.pine --timeframe 1h --no-magnify

# JSON output for programmatic use
python -m backtest --script backtest/strategies/rsi_overbought.pine --timeframe 1d --json

Terraform¶

cd terraform

# Initialize
terraform init

# Plan changes
terraform plan -var-file="prod.tfvars"

# Apply
terraform apply -var-file="prod.tfvars"

正式環境安全

套用前務必檢查 terraform plan 輸出結果。平台管理約 80 項 AWS 資源，包括 ECS 叢集、Lambda 函式、SQS 佇列和 IAM 角色。