# Docker 容器测试和迁移指南 **日期**: 2026-02-07 **适用于**: AI Prompt System v2.0 增强功能 --- ## 📋 前置条件 确保 Docker 容器已启动： ```bash cd /Users/panta/py_work/jointoai_work/Jointoai docker compose up -d ``` 检查容器状态： ```bash docker compose ps ``` --- ## 🗄️ 数据库迁移 ### 1. 进入后端容器 ```bash docker compose exec backend bash ``` ### 2. 运行迁移（如果有新的迁移文件） ```bash # 在容器内执行 cd /app alembic upgrade head ``` ### 3. 验证迁移状态 ```bash # 查看当前迁移版本 alembic current # 查看迁移历史 alembic history ``` ### 4. 同步 AI Skills 到数据库 ```bash # 在容器内执行 python scripts/sync_ai_skills.py # 查看已注册的技能 python scripts/sync_ai_skills.py --list ``` --- ## 🧪 运行测试 ### 1. 运行所有单元测试 ```bash # 在容器内执行 cd /app pytest tests/unit/ -v ``` ### 2. 运行特定模块的测试 #### Schema 参数验证测试 ```bash pytest tests/unit/schemas/test_screenplay_parse_request.py -v ``` #### Service 层参数传递测试 ```bash pytest tests/unit/services/test_ai_service_parse_screenplay.py -v ``` #### API 集成测试 ```bash pytest tests/integration/test_screenplay_api.py::TestScreenplayAPI::test_parse_screenplay_with_custom_requirements -v pytest tests/integration/test_screenplay_api.py::TestScreenplayAPI::test_parse_screenplay_storyboard_count_validation -v ``` ### 3. 运行所有集成测试 ```bash pytest tests/integration/ -v ``` ### 4. 运行带覆盖率的测试 ```bash # 安装 pytest-cov（如果未安装） pip install pytest-cov # 运行测试并生成覆盖率报告 pytest tests/unit/ --cov=app --cov-report=html --cov-report=term # 查看覆盖率报告 # 报告生成在 htmlcov/index.html ``` ### 5. 运行特定测试并显示详细日志 ```bash pytest tests/unit/schemas/test_screenplay_parse_request.py -v -s --log-cli-level=INFO ``` --- ## 🔍 快速验证脚本 ### 一键运行所有新增功能测试 ```bash #!/bin/bash # 在容器内执行 echo "======================================" echo "测试 1: Schema 参数验证" echo "======================================" pytest tests/unit/schemas/test_screenplay_parse_request.py -v echo "" echo "======================================" echo "测试 2: Service 层参数传递" echo "======================================" pytest tests/unit/services/test_ai_service_parse_screenplay.py -v echo "" echo "======================================" echo "测试 3: API 集成测试" echo "======================================" pytest tests/integration/test_screenplay_api.py -k "parse_screenplay_with_custom" -v echo "" echo "======================================" echo "所有测试完成！" echo "======================================" ``` 保存为 `/app/scripts/test_new_features.sh`，然后运行： ```bash chmod +x scripts/test_new_features.sh ./scripts/test_new_features.sh ``` --- ## 🐛 常见问题排查 ### 1. 导入错误 **问题**: `ModuleNotFoundError: No module named 'app'` **解决**: ```bash # 确保在 /app 目录下 cd /app # 设置 PYTHONPATH export PYTHONPATH=/app:$PYTHONPATH ``` ### 2. 数据库连接错误 **问题**: `Connection refused` 或 `could not connect to server` **解决**: ```bash # 检查 PostgreSQL 容器状态 docker compose ps db # 查看数据库日志 docker compose logs db # 重启数据库 docker compose restart db ``` ### 3. 测试数据库配置 **确保使用测试数据库**: ```python # conftest.py 中应该有： @pytest.fixture(scope="session") def database_url(): """测试数据库 URL""" return os.getenv("TEST_DATABASE_URL", "postgresql+asyncpg://...") ``` ### 4. Celery 任务 Mock 失败 **问题**: 测试中 Celery 任务未被正确 Mock **解决**: ```python # 确保 patch 路径正确 with patch('app.services.ai_service.parse_screenplay_task') as mock_task: # 而不是 # with patch('app.tasks.ai_tasks.parse_screenplay_task') ``` --- ## 📊 测试输出示例 ### 成功输出 ``` tests/unit/schemas/test_screenplay_parse_request.py::TestScreenplayParseRequest::test_default_values PASSED [ 10%] tests/unit/schemas/test_screenplay_parse_request.py::TestScreenplayParseRequest::test_custom_requirements_valid PASSED [ 20%] tests/unit/schemas/test_screenplay_parse_request.py::TestScreenplayParseRequest::test_storyboard_count_valid PASSED [ 30%] ... ========== 15 passed in 2.34s ========== ``` ### 失败输出（需要修复） ``` tests/unit/schemas/test_screenplay_parse_request.py::TestScreenplayParseRequest::test_storyboard_count_below_minimum FAILED [ 40%] E ValidationError: 1 validation error for ScreenplayParseRequest E storyboard_count E Input should be greater than or equal to 3 [type=greater_than_equal, input_value=2, input_type=int] ``` --- ## 🚀 完整工作流 ### 开发流程 ```bash # 1. 启动容器 docker compose up -d # 2. 进入后端容器 docker compose exec backend bash # 3. 运行迁移 alembic upgrade head # 4. 同步 AI Skills python scripts/sync_ai_skills.py # 5. 运行测试 pytest tests/unit/ -v pytest tests/integration/ -v -k "parse_screenplay" # 6. 检查代码质量 flake8 app/schemas/screenplay.py mypy app/services/ai_service.py # 7. 查看日志 exit # 退出容器 docker compose logs -f backend ``` ### CI/CD 流程 ```yaml # .github/workflows/test.yml name: Test on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Start containers run: docker compose up -d - name: Run migrations run: docker compose exec -T backend alembic upgrade head - name: Sync AI Skills run: docker compose exec -T backend python scripts/sync_ai_skills.py - name: Run tests run: | docker compose exec -T backend pytest tests/unit/ -v docker compose exec -T backend pytest tests/integration/ -v - name: Cleanup run: docker compose down -v ``` --- ## 📝 手动测试 API ### 使用 cURL ```bash # 1. 获取 Token（在宿主机执行） TOKEN=$(curl -X POST "http://localhost:6170/api/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{"phone":"13800138000","password":"test123"}' \ | jq -r '.data.token') # 2. 创建测试剧本 SCREENPLAY_ID=$(curl -X POST "http://localhost:6170/api/v1/screenplays" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "projectId": "your-project-id", "name": "测试剧本", "content": "这是一个测试剧本内容..." }' | jq -r '.data.screenplayId') # 3. 测试新参数的解析接口 curl -X POST "http://localhost:6170/api/v1/screenplays/$SCREENPLAY_ID/parse" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customRequirements": "增加人物特写镜头，注重情感表达", "storyboardCount": 8, "model": "gpt-4" }' | jq '.' # 4. 查询任务状态 JOB_ID="返回的jobId" curl "http://localhost:6170/api/v1/ai/jobs/$JOB_ID" \ -H "Authorization: Bearer $TOKEN" | jq '.' ``` --- ## 🔧 调试技巧 ### 1. 进入容器调试 ```bash # 进入容器 docker compose exec backend bash # 使用 IPython 交互式调试 pip install ipython ipython # 在 IPython 中 from app.services.ai_service import AIService from app.core.database import get_session # 测试代码... ``` ### 2. 查看实时日志 ```bash # 宿主机执行 docker compose logs -f backend # 过滤特定关键词 docker compose logs -f backend | grep "剧本解析" ``` ### 3. 数据库查询 ```bash # 进入 PostgreSQL 容器 docker compose exec db psql -U jointo -d jointo # 查询 AI Skills SELECT skill_id, name, version, is_active FROM ai_skills_registry; # 查询 AI Jobs SELECT ai_job_id, job_type, status, created_at FROM ai_jobs ORDER BY created_at DESC LIMIT 10; ``` --- ## ✅ 验收检查清单 - [ ] 所有单元测试通过 - [ ] 所有集成测试通过 - [ ] AI Skills 同步成功 - [ ] API 接口返回正确 - [ ] 日志输出正常 - [ ] 无 Lint 错误 - [ ] 数据库迁移成功 - [ ] Docker 容器运行正常 --- **维护人员**: AI Agent **最后更新**: 2026-02-07