ctms/docs/reports/docker-fix-report.md

Docker 启动问题修复报告

修复日期: 2026-05-14
修复状态: ✅ 完成

---

问题概述

Docker Compose 启动失败，前端编译错误和后端导入错误导致服务无法启动。

---

修复内容

1. 前端 SCSS 编译依赖问题

问题: npm run build 失败，提示缺少 sass-embedded 依赖

原因: 新增的 Vue 组件（ApiPermissions.vue、PermissionMonitoring.vue 等）使用了 SCSS 样式，但 package.json 中没有安装 sass-embedded

修复:

// frontend/package.json
{
  "devDependencies": {
    "sass-embedded": "^1.77.0"  // 新增
  }
}

文件: frontend/package.json

---

2. Vite 路径别名配置问题

问题: Vite 构建时无法解析 @/ 路径别名，导致导入失败

原因: vite.config.ts 缺少 resolve.alias 配置

修复:

// 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 中的函数
• 形成了循环导入

修复: 使用延迟导入，在方法内部导入所需的函数

# 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 末尾添加常量定义

# backend/app/core/api_permissions.py
PROJECT_PERMISSION_ROLES = ["PM", "CRA", "PV", "MEDICAL_REVIEW", "IMP"]

文件: 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