ADR-003：Docker Compose 为项目编排入口

Date

2026-10-29

Status

Accepted。用户在实施过程中明确提出“你应该考虑使用 Docker 进行排布。”；本决定落实宪法既定 Docker 部署方向，不扩大业务范围。

Context

单机基础平台需要统一 PostgreSQL、core、web 与同源入口。前轮环境检查只发现 PATH 缺少 Docker 命令，并未证明软件未安装；本轮核实已有 Docker CLI、Compose、Colima，但无运行中的引擎。

Decision

在 infra/ 交付 Compose、nginx 统一入口和 secret 准备脚本；core/web 各自包含多阶段 Dockerfile。只有 gateway 发布 loopback 入口，数据库命名卷持久化、数据库网络内部隔离，应用以非 root 和只读根文件系统运行。

nginx 只转发请求，不裁决身份或业务权限。选择官方 nginx 的理由是固定转发配置即可满足同源入口，避免把路由与业务放进 web；不引入 K8s、网关业务插件或通用服务发现平台。

本机使用新建 Colima lab-edu profile；不切换默认 context，不改原有 default 实例。只读挂载新项目 infra 目录以支持配置与文件型 secret，不读取 GitLab 旧仓库。

Consequences

需要区分 compose config、基础组件运行和产品全栈联调；前两者不能代替后者。core 镜像打包使用 -DskipTests，验收必须单独运行。本机实际工具为 Docker CLI 29.9.2、专用引擎 29.2.1、Compose 5.1.4；记录实际兼容工具，不伪报成 CLI 2.x。

本地 HTTP 需显式叠加 compose.local.yaml；公网部署需要 TLS 且保持 Secure Cookie。secret 目录不入库，修改文件不自动修改既有数据库密码；日常停止不删除数据卷。

Reverts

更换编排或入口方案需新 ADR；不得通过迁移恢复旧 GitLab 项目历史。测试结束可停止专用实例而保留新项目数据卷。