H3ConuMS-v2/docs/CI实施说明.md

CI 实施说明

本仓库提供 .gitlab-ci.yml，用于满足 C1 项目最小的代码更新、构建、测试和依赖安全检查能力。流水线在合并请求、分支更新和标签创建时运行；受保护分支应在 GitLab 中配置为仅允许通过流水线和评审合入。

发布前配置

在 GitLab 项目的 CI/CD 变量中配置以下受保护且掩码变量：

变量	用途	要求
INTERNAL_PYPI_URL	企业统一 PyPI 代理地址	仅允许访问经批准的代理仓库；不得配置为个人镜像。
INTERNAL_NPM_REGISTRY	企业统一 npm 代理地址	仅允许访问经批准的代理仓库；不得提交认证令牌到仓库。
INTERNAL_CONTAINER_PROXY	企业统一容器镜像代理地址（不含末尾 /）	Runner、构建基础镜像和 Docker-in-Docker 均从该代理拉取镜像。

流水线会在变量缺失时失败，避免从非受控公共源下载依赖或基础镜像。若代理需要认证，应使用 GitLab 受保护变量或 Runner 的受控凭据注入机制，不得将账号、口令或 token 写入 .gitlab-ci.yml、requirements.txt、package-lock.json、Dockerfile 或日志。

流水线内容与门禁

1. dependency-source-policy：验证统一依赖源已配置。
2. backend-tests：安装锁定的 Python 依赖，执行语法检查和 pytest，归档 JUnit 报告。
3. frontend-build：通过 npm ci 使用锁文件构建前端，归档静态构建产物。
4. python-dependency-audit：执行 Python 第三方组件漏洞扫描，归档 JSON 报告；发现可识别漏洞时失败。
5. container-build：仅构建带 commit SHA 标签的后端与前端镜像，验证 Dockerfile 可构建；Python、npm 与基础镜像均从企业代理获得，本 job 不推送镜像。

容器构建依赖 Docker-in-Docker runner。若当前 Runner 未授权特权容器，应由平台管理员提供隔离的构建 Runner；不得为了通过流水线而取消镜像构建或将 Docker Socket 暴露给不受信任的 job。

仍需由平台完成的事项

• 在 GitLab 中开启合并请求评审与成功流水线门禁，并保护 main/发布分支。
• 增加平台 SAST、前端依赖/SCA、许可证扫描和镜像扫描 job，并把报告关联到统一制品库中的制品元数据。
• 将镜像推送至统一制品库，采用不可变版本（发布 tag + commit SHA）并记录制品、测试、扫描和部署关联；该动作需要制品库地址与发布权限，未在本次整改中写入。