chore: add environment variable support and enhance startup script

- Add .env.example template for configurable Docker deployment settings
- Update docker-compose.yml to support environment-driven port/timezone configuration
- Refactor start.sh with improved Docker Compose detection, environment validation, and automated frontend building
- Enhance script documentation and error handling for better maintainability

.env.example

@@ -0,0 +1,13 @@
+# NOFX Environment Variables Template
+# Copy this file to .env and modify the values as needed
+
+# Ports Configuration
+# Backend API server port (internal: 8080, external: configurable)
+NOFX_BACKEND_PORT=8080
+
+# Frontend web interface port (Nginx listens on port 80 internally)
+NOFX_FRONTEND_PORT=3000
+
+# Timezone Setting
+# System timezone for container time synchronization
+NOFX_TIMEZONE=Asia/Shanghai

.gitignore

@@ -21,6 +21,7 @@ Thumbs.db
 *.log
 *.tmp
 *.bak
+*.backup
 
 # 环境变量
 .env

docker-compose.yml

@@ -9,13 +9,13 @@ services:
     container_name: nofx-trading
     restart: unless-stopped
     ports:
-      - "8080:8080"
+      - "${NOFX_BACKEND_PORT:-8080}:8080"
     volumes:
       - ./config.json:/app/config.json:ro
       - ./decision_logs:/app/decision_logs
       - /etc/localtime:/etc/localtime:ro  # 同步主机时间
     environment:
-      - TZ=Asia/Shanghai  # 使用中国时区
+      - TZ=${NOFX_TIMEZONE:-Asia/Shanghai}  # 使用中国时区
     networks:
       - nofx-network
     healthcheck:
@@ -31,7 +31,7 @@ services:
     container_name: nofx-frontend
     restart: unless-stopped
     ports:
-      - "3000:80"
+      - "${NOFX_FRONTEND_PORT:-3000}:80"
     volumes:
       - ./web/dist:/usr/share/nginx/html:ro
       - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

start.sh

@@ -1,18 +1,24 @@
 #!/bin/bash
 
+# ═══════════════════════════════════════════════════════════════
 # NOFX AI Trading System - Docker Quick Start Script
-# 使用方法: ./start.sh [command]
+# Usage: ./start.sh [command]
+# ═══════════════════════════════════════════════════════════════
 
 set -e
 
-# 颜色定义
+# ------------------------------------------------------------------------
+# Color Definitions
+# ------------------------------------------------------------------------
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-# 打印带颜色的消息
+# ------------------------------------------------------------------------
+# Utility Functions: Colored Output
+# ------------------------------------------------------------------------
 print_info() {
     echo -e "${BLUE}[INFO]${NC} $1"
 }
@@ -29,22 +35,51 @@ print_error() {
     echo -e "${RED}[ERROR]${NC} $1"
 }
 
-# 检查 Docker 是否安装
+# ------------------------------------------------------------------------
+# Detection: Docker Compose Command (Backward Compatible)
+# ------------------------------------------------------------------------
+detect_compose_cmd() {
+    if command -v docker compose &> /dev/null; then
+        COMPOSE_CMD="docker compose"
+    elif command -v docker-compose &> /dev/null; then
+        COMPOSE_CMD="docker-compose"
+    else
+        print_error "Docker Compose 未安装！请先安装 Docker Compose"
+        exit 1
+    fi
+    print_info "使用 Docker Compose 命令: $COMPOSE_CMD"
+}
+
+# ------------------------------------------------------------------------
+# Validation: Docker Installation
+# ------------------------------------------------------------------------
 check_docker() {
     if ! command -v docker &> /dev/null; then
         print_error "Docker 未安装！请先安装 Docker: https://docs.docker.com/get-docker/"
         exit 1
     fi
 
-    if ! command -v docker-compose &> /dev/null; then
-        print_error "Docker Compose 未安装！请先安装 Docker Compose"
-        exit 1
-    fi
-
+    detect_compose_cmd
     print_success "Docker 和 Docker Compose 已安装"
 }
 
-# 检查配置文件
+# ------------------------------------------------------------------------
+# Validation: Environment File (.env)
+# ------------------------------------------------------------------------
+check_env() {
+    if [ ! -f ".env" ]; then
+        print_warning ".env 不存在，从模板复制..."
+        cp .env.example .env
+        print_info "请编辑 .env 填入你的环境变量配置"
+        print_info "运行: nano .env 或使用其他编辑器"
+        exit 1
+    fi
+    print_success "环境变量文件存在"
+}
+
+# ------------------------------------------------------------------------
+# Validation: Configuration File (config.json)
+# ------------------------------------------------------------------------
 check_config() {
     if [ ! -f "config.json" ]; then
         print_warning "config.json 不存在，从模板复制..."
@@ -56,15 +91,53 @@ check_config() {
     print_success "配置文件存在"
 }
 
-# 启动服务
+# ------------------------------------------------------------------------
+# Build: Frontend (Node.js Based)
+# ------------------------------------------------------------------------
+build_frontend() {
+    print_info "检查前端构建环境..."
+
+    if ! command -v node &> /dev/null; then
+        print_error "Node.js 未安装！请先安装 Node.js"
+        exit 1
+    fi
+
+    if ! command -v npm &> /dev/null; then
+        print_error "npm 未安装！请先安装 npm"
+        exit 1
+    fi
+
+    print_info "正在构建前端..."
+    cd web
+
+    print_info "安装 Node.js 依赖..."
+    npm install
+
+    print_info "构建前端应用..."
+    npm run build
+
+    cd ..
+    print_success "前端构建完成"
+}
+
+# ------------------------------------------------------------------------
+# Service Management: Start
+# ------------------------------------------------------------------------
 start() {
     print_info "正在启动 NOFX AI Trading System..."
 
+    # Auto-build frontend if missing or forced
+    if [ ! -d "web/dist" ] || [ "$1" == "--build" ]; then
+        build_frontend
+    fi
+
+    # Rebuild images if flag set
     if [ "$1" == "--build" ]; then
         print_info "重新构建镜像..."
-        docker-compose up -d --build
+        $COMPOSE_CMD up -d --build
     else
-        docker-compose up -d
+        print_info "启动容器..."
+        $COMPOSE_CMD up -d
     fi
 
     print_success "服务已启动！"
@@ -75,60 +148,74 @@ start() {
     print_info "停止服务: ./start.sh stop"
 }
 
-# 停止服务
+# ------------------------------------------------------------------------
+# Service Management: Stop
+# ------------------------------------------------------------------------
 stop() {
     print_info "正在停止服务..."
-    docker-compose stop
+    $COMPOSE_CMD stop
     print_success "服务已停止"
 }
 
-# 重启服务
+# ------------------------------------------------------------------------
+# Service Management: Restart
+# ------------------------------------------------------------------------
 restart() {
     print_info "正在重启服务..."
-    docker-compose restart
+    $COMPOSE_CMD restart
     print_success "服务已重启"
 }
 
-# 查看日志
+# ------------------------------------------------------------------------
+# Monitoring: Logs
+# ------------------------------------------------------------------------
 logs() {
     if [ -z "$2" ]; then
-        docker-compose logs -f
+        $COMPOSE_CMD logs -f
     else
-        docker-compose logs -f "$2"
+        $COMPOSE_CMD logs -f "$2"
     fi
 }
 
-# 查看状态
+# ------------------------------------------------------------------------
+# Monitoring: Status
+# ------------------------------------------------------------------------
 status() {
     print_info "服务状态:"
-    docker-compose ps
+    $COMPOSE_CMD ps
     echo ""
     print_info "健康检查:"
     curl -s http://localhost:8080/health | jq '.' || echo "后端未响应"
 }
 
-# 清理
+# ------------------------------------------------------------------------
+# Maintenance: Clean (Destructive)
+# ------------------------------------------------------------------------
 clean() {
     print_warning "这将删除所有容器和数据！"
     read -p "确认删除？(yes/no): " confirm
     if [ "$confirm" == "yes" ]; then
         print_info "正在清理..."
-        docker-compose down -v
+        $COMPOSE_CMD down -v
         print_success "清理完成"
     else
         print_info "已取消"
     fi
 }
 
-# 更新
+# ------------------------------------------------------------------------
+# Maintenance: Update
+# ------------------------------------------------------------------------
 update() {
     print_info "正在更新..."
     git pull
-    docker-compose up -d --build
+    $COMPOSE_CMD up -d --build
     print_success "更新完成"
 }
 
-# 显示帮助
+# ------------------------------------------------------------------------
+# Help: Usage Information
+# ------------------------------------------------------------------------
 show_help() {
     echo "NOFX AI Trading System - Docker 管理脚本"
     echo ""
@@ -150,12 +237,15 @@ show_help() {
     echo "  ./start.sh status           # 查看状态"
 }
 
-# 主函数
+# ------------------------------------------------------------------------
+# Main: Command Dispatcher
+# ------------------------------------------------------------------------
 main() {
     check_docker
 
     case "${1:-start}" in
         start)
+            check_env
             check_config
             start "$2"
             ;;
@@ -188,5 +278,5 @@ main() {
     esac
 }
 
-# 运行主函数
-main "$@"
+# Execute Main
+main "$@"