ljwx-study/CONFIG_GUIDE.md

配置管理指南

概述

本项目已全面移除硬编码配置，所有配置均从环境变量文件 .env 读取，确保部署的灵活性和安全性。

配置文件结构

1. 主配置文件：.env（项目根目录）

所有环境配置的中心文件，包含前后端所有配置项。

# ==========================================
# Application Configuration
# ==========================================
BACKEND_PORT=8888
FRONTEND_PORT=3008

# ==========================================
# Backend API Configuration
# ==========================================
API_URL=http://localhost:8888
SECRET_KEY=your-super-secret-and-secure-key-change-me
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# ==========================================
# Database Configuration
# ==========================================
DATABASE_URL=postgresql://localhost:5432/wordmaster
DB_HOST=localhost
DB_PORT=5432
DB_NAME=wordmaster
DB_USER=postgres
DB_PASSWORD=postgres

# ==========================================
# Frontend Vite Configuration
# ==========================================
VITE_API_BASE_URL=/api
VITE_FILE_BASE_URL=/api
VITE_WS_BASE_URL=ws://localhost:8888/ws
VITE_BACKEND_HOST=localhost
VITE_BACKEND_PORT=8888
VITE_SERVER_PORT=3008
VITE_DEBUG=true
VITE_LOG_LEVEL=debug
VITE_APP_VERSION=1.0.0

# ==========================================
# OpenRouter AI Configuration
# ==========================================
OPENROUTER_API_KEY=your-api-key-here

2. 前端开发配置：frontend/.env.development

前端开发环境专用配置，Vite会自动加载。

已修复的硬编码位置

后端 (backend/)

1. backend/main.py

修复内容:

• 添加 BACKEND_PORT 和 API_URL 环境变量读取
• 修复 upload_url 动态构建（第806行）
• 修复 uvicorn.run() 端口配置（第2110行）

修改前:

upload_url=f"http://localhost:8888/api/file/upload/{file_key}"
uvicorn.run(app, host="0.0.0.0", port=8888)

修改后:

BACKEND_PORT = int(os.getenv("BACKEND_PORT", "8888"))
API_URL = os.getenv("API_URL", f"http://localhost:{BACKEND_PORT}")

upload_url=f"{API_URL}/api/file/upload/{file_key}"
uvicorn.run(app, host="0.0.0.0", port=BACKEND_PORT)

2. 测试文件

• backend/test_all_fixes.py
• backend/test_frontend_fixes.py
• backend/test_split_api.py

修改: 所有测试脚本的 BASE_URL 现在从环境变量读取。

前端 (frontend/)

1. frontend/vite.config.js

修复内容: 端口配置从环境变量读取

修改前:

server: {
  host: '0.0.0.0',
  port: 3000,  // 硬编码

修改后:

server: {
  host: '0.0.0.0',
  port: parseInt(env.VITE_SERVER_PORT) || 3000,  // 从环境变量读取

2. frontend/src/config/index.js

修复内容: 所有环境配置的8888端口改为从 VITE_BACKEND_PORT 读取

修改示例:

// 修改前
WS_BASE_URL: 'ws://localhost:8888/ws'

// 修改后
WS_BASE_URL: import.meta.env.VITE_WS_BASE_URL ||
  `ws://localhost:${import.meta.env.VITE_BACKEND_PORT || '8888'}/ws`

3. frontend/src/views/PaperViewer.vue

修复内容: 图片URL构建逻辑改为从环境变量读取端口

修改前:

let baseUrl = 'http://localhost:8888'  // 硬编码

修改后:

const backendPort = import.meta.env.VITE_BACKEND_PORT || '8888'
let baseUrl = `http://localhost:${backendPort}`

如何修改配置

开发环境

1. 编辑项目根目录的 .env 文件
2. 修改所需的配置项
3. 重启应用：./stop_app.sh && ./start_app.sh

生产环境

1. 创建 .env.production 文件
2. 设置生产环境专用配置：

BACKEND_PORT=8000
FRONTEND_PORT=80
DATABASE_URL=postgresql://prod_user:password@db-server:5432/wordmaster
SECRET_KEY=production-secret-key-very-secure
VITE_BACKEND_PORT=8000

3. 部署时确保环境变量正确加载

更改端口示例

场景: 将后端端口从8888改为9000

1. 编辑 .env:

BACKEND_PORT=9000
API_URL=http://localhost:9000
VITE_BACKEND_PORT=9000
VITE_WS_BASE_URL=ws://localhost:9000/ws

2. 编辑 frontend/.env.development:

VITE_BACKEND_PORT=9000
VITE_WS_BASE_URL=ws://localhost:9000/ws

3. 重启服务：

./stop_app.sh
./start_app.sh

配置优先级

后端 (Python)

1. 环境变量（最高优先级）
2. .env 文件
3. 代码中的默认值（兜底）

前端 (Vite)

1. import.meta.env.VITE_* 环境变量（最高优先级）
2. .env.development / .env.production
3. 代码中的默认值（兜底）

验证配置是否生效

1. 检查进程启动参数

# 检查后端端口
ps aux | grep uvicorn | grep -o "port [0-9]*"

# 检查前端端口
ps aux | grep vite | grep -o "\-\-port [0-9]*"

2. 检查端口监听

lsof -i :8888  # 后端端口
lsof -i :3008  # 前端端口

3. 访问测试

# 测试后端
curl http://localhost:8888/docs

# 测试前端
curl http://localhost:3008/

环境变量命名规范

后端环境变量

• 直接使用大写名称：BACKEND_PORT, DATABASE_URL, SECRET_KEY
• 在 backend/main.py 中通过 os.getenv() 读取

前端环境变量

• 必须以 VITE_ 开头：VITE_BACKEND_PORT, VITE_API_BASE_URL
• 在前端代码中通过 import.meta.env.VITE_* 访问
• Vite 编译时会将这些变量内联到代码中

常见问题

Q1: 修改了.env文件，配置没有生效？

A: 需要重启服务。运行 ./stop_app.sh && ./start_app.sh

Q2: 前端无法连接后端API？

A: 检查以下配置是否一致：

• .env 中的 BACKEND_PORT
• .env 中的 VITE_BACKEND_PORT
• frontend/.env.development 中的 VITE_BACKEND_PORT

Q3: 如何在不同环境使用不同配置？

A: 创建多个环境配置文件：

• .env.development - 开发环境
• .env.staging - 测试环境
• .env.production - 生产环境

启动时指定环境：

NODE_ENV=production ./start_app.sh

安全建议

1. 不要提交敏感信息: .env 文件应该添加到 .gitignore
2. 使用强密钥: SECRET_KEY 必须在生产环境中更改为强随机字符串
3. 限制CORS: 生产环境不要使用 allow_origins=["*"]
4. 数据库密码: 使用环境变量，不要硬编码
5. API密钥: OPENROUTER_API_KEY 等敏感信息仅存储在服务器环境变量中

配置检查清单

• .env 文件已创建并配置
• frontend/.env.development 已配置
• 所有端口配置一致
• 数据库连接信息正确
• API密钥已配置（如需要）
• 重启服务后配置生效
• 前后端可以正常通信
• WebSocket连接正常（如使用）

修改记录

• 2025-11-16: 全面移除硬编码，所有配置改为从.env读取
  • 修复了 backend/main.py 中的端口和URL硬编码
  • 修复了 frontend/vite.config.js 的端口硬编码
  • 修复了 frontend/src/config/index.js 的API地址硬编码
  • 修复了 frontend/src/views/PaperViewer.vue 的图片URL硬编码
  • 更新了所有测试文件
  • 完善了 .env 配置文件结构