stock_cursor_v0/backend/CHECKLIST.md

启动前检查清单

在首次启动或遇到问题时，请按此清单逐项检查。

✅ 环境检查

系统服务

# PostgreSQL 是否运行
sudo service postgresql status
sudo service postgresql start  # 如果未运行

# Redis 是否运行
redis-cli ping  # 应返回 PONG
sudo service redis-server start  # 如果未运行

Python 环境

# 虚拟环境是否激活
which python  # 应显示 .venv/bin/python
source .venv/bin/activate  # 如果未激活

# 依赖是否安装完整
pip list | grep redis
pip list | grep jose
pip list | grep passlib

✅ 配置检查

.env 文件

# 检查必要配置项
cat .env | grep PG_PASSWORD
cat .env | grep SECRET_KEY
cat .env | grep REDIS_HOST

# 如果缺少配置
cp .env.example .env  # 如果 .env 不存在
nano .env  # 编辑配置

必须配置的项

• PG_PASSWORD - PostgreSQL 密码
• SECRET_KEY - JWT 密钥（生产环境必须修改）
• REDIS_HOST - Redis 地址（默认 localhost）

✅ 数据库检查

# 检查数据库是否创建
psql -U postgres -c "\l" | grep stock_cs

# 检查用户表是否存在
psql -U postgres -d stock_cs -c "\dt" | grep users

# 如果数据库或表不存在
python cli.py init

✅ 权限检查

# 测试数据库连接
psql -U postgres -d stock_cs -c "SELECT 1;"

# 测试 Redis 连接
redis-cli ping

# 如果提示权限错误
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"

✅ 启动服务

# 完整启动流程
sudo service postgresql start
sudo service redis-server start
cd backend
source .venv/bin/activate
python main.py

启动成功标志

看到以下日志表示启动成功：

✓ Redis 已连接: localhost:6379
✓ 管理员账号已存在: admin
[startup] db + scheduler + auth ready
INFO:     Uvicorn running on http://0.0.0.0:8000

✅ 功能测试

# 1. 健康检查
curl http://localhost:8000/api/health
# 应返回: {"ok":true,"akshare":true,"redis":true,"auth":true}

# 2. 登录测试
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
# 应返回 Token

# 3. 运行完整测试
python test_core_features.py

🔧 常见问题排查

问题 1: Redis 连接失败

✗ Redis 连接失败，缓存已禁用

解决:

sudo service redis-server start
redis-cli ping

问题 2: 数据库连接失败

connection refused

解决:

sudo service postgresql start
psql -U postgres -c "SELECT 1;"

问题 3: 密码认证失败

password authentication failed

解决:

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"
# 然后在 .env 中设置相同的密码

问题 4: 模块未找到

ModuleNotFoundError: No module named 'redis'

解决:

source .venv/bin/activate
pip install -r requirements.txt

问题 5: 401 Unauthorized

{"detail":"未认证，请先登录"}

解决:

# 先登录获取 Token
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 使用 Token 访问
curl -X GET http://localhost:8000/api/admin/status \
  -H "Authorization: Bearer <返回的token>"

问题 6: 用户表不存在

relation "users" does not exist

解决:

python cli.py init

📝 首次部署完整流程

# 1. 系统依赖
sudo apt update
sudo apt install -y postgresql redis-server

# 2. 启动服务
sudo service postgresql start
sudo service redis-server start

# 3. 配置数据库密码
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"

# 4. Python 环境
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 5. 配置环境变量
cp .env.example .env
nano .env  # 编辑 PG_PASSWORD, SECRET_KEY 等

# 6. 初始化数据库
python cli.py init

# 7. 启动服务
python main.py

# 8. 测试
python test_core_features.py

🚀 一键启动脚本（WSL）

创建 start.sh:

#!/bin/bash
sudo service postgresql start
sudo service redis-server start
cd /mnt/e/project/stock_cs_v1/backend  # 修改为实际路径
source .venv/bin/activate
python main.py

使用:

chmod +x start.sh
./start.sh

📞 获取帮助

如果以上方法都无法解决问题:

1. 查看详细文档: backend/UPGRADE_GUIDE.md
2. 查看配置说明: backend/ENV_CONFIG.md
3. 查看实现总结: 三大核心功能实现总结.md