diff --git a/DOCKER_FIX_REPORT.md b/DOCKER_FIX_REPORT.md new file mode 100644 index 00000000..8cb6fd4e --- /dev/null +++ b/DOCKER_FIX_REPORT.md @@ -0,0 +1,159 @@ +# Docker 启动问题修复报告 + +**修复日期**: 2026-05-14 +**修复状态**: ✅ **完成** + +--- + +## 问题概述 + +Docker Compose 启动失败,前端编译错误和后端导入错误导致服务无法启动。 + +--- + +## 修复内容 + +### 1. 前端 SCSS 编译依赖问题 + +**问题**: `npm run build` 失败,提示缺少 `sass-embedded` 依赖 + +**原因**: 新增的 Vue 组件(ApiPermissions.vue、PermissionMonitoring.vue 等)使用了 SCSS 样式,但 package.json 中没有安装 sass-embedded + +**修复**: +```json +// frontend/package.json +{ + "devDependencies": { + "sass-embedded": "^1.77.0" // 新增 + } +} +``` + +**文件**: `frontend/package.json` + +--- + +### 2. Vite 路径别名配置问题 + +**问题**: Vite 构建时无法解析 `@/` 路径别名,导致导入失败 + +**原因**: `vite.config.ts` 缺少 `resolve.alias` 配置 + +**修复**: +```typescript +// frontend/vite.config.ts +import { fileURLToPath } from "node:url"; + +export default defineConfig({ + resolve: { + alias: { + "@": fileURLToPath(new URL("./src", import.meta.url)), + }, + }, +}); +``` + +**文件**: `frontend/vite.config.ts` + +--- + +### 3. 后端循环导入问题 + +**问题**: 后端启动时出现循环导入错误 + +``` +ImportError: cannot import name 'get_project_role_permissions' from partially initialized module 'app.core.project_permissions' +``` + +**原因**: +- `permission_cache.py` 在模块级别导入 `project_permissions.py` 中的函数 +- `project_permissions.py` 也导入 `permission_cache.py` 中的函数 +- 形成了循环导入 + +**修复**: 使用延迟导入,在方法内部导入所需的函数 + +```python +# backend/app/core/permission_cache.py +async def get_project_role_permissions(self, db, study_id, ttl=None): + # 延迟导入,避免循环导入 + from app.core.project_permissions import get_project_role_permissions as _get_project_role_permissions + + # ... 使用 _get_project_role_permissions +``` + +**文件**: `backend/app/core/permission_cache.py` + +--- + +### 4. 后端缺失常量问题 + +**问题**: 导入错误,缺少 `PROJECT_PERMISSION_ROLES` 常量 + +``` +ImportError: cannot import name 'PROJECT_PERMISSION_ROLES' from 'app.core.api_permissions' +``` + +**原因**: `api_permissions.py` 中定义了 `API_ENDPOINT_PERMISSIONS` 但没有定义 `PROJECT_PERMISSION_ROLES`,而 `api_permissions.py` 路由文件需要导入这个常量 + +**修复**: 在 `api_permissions.py` 末尾添加常量定义 + +```python +# backend/app/core/api_permissions.py +PROJECT_PERMISSION_ROLES = ["PM", "CRA", "PV", "MEDICAL_REVIEW", "IMP", "QA"] +``` + +**文件**: `backend/app/core/api_permissions.py` + +--- + +## 修复提交 + +| 提交 | 文件 | 说明 | +|------|------|------| +| 77b16ffa | frontend/package.json | 添加 sass-embedded 依赖 | +| 7b397640 | frontend/vite.config.ts | 添加 Vite 路径别名配置 | +| fdf64069 | backend/app/core/permission_cache.py | 解决循环导入问题 | +| 50106452 | backend/app/core/api_permissions.py | 添加缺失的常量 | + +--- + +## 验证结果 + +### 服务状态 + +``` +NAME IMAGE STATUS +ctms_backend ctms_dev-backend Up (健康) +ctms_db postgres:15-alpine Up (健康) +ctms_nginx ctms_dev-nginx Up (健康) +``` + +### 功能验证 + +✅ 前端编译成功 +✅ 后端启动成功 +✅ Nginx 代理正常 +✅ 数据库连接正常 +✅ 应用可访问 + +### 访问方式 + +- **前端应用**: http://localhost:8888 +- **后端 API**: http://localhost:8000 +- **数据库**: localhost:5432 + +--- + +## 总结 + +所有 Docker 启动问题都已修复,应用现在可以正常启动和运行。修复涉及: + +1. **前端依赖**: 添加 SCSS 编译器依赖 +2. **前端配置**: 配置路径别名解析 +3. **后端代码**: 解决循环导入和缺失常量问题 + +所有修复都是最小化的,不影响现有功能,只是补充了缺失的配置和依赖。 + +--- + +**修复完成**: ✅ 2026-05-14