refactor(GOV-009): 彻底切换为仅源码部署

2026-08-13 21:12:12 +08:00
parent ab48f06150
commit 47d0e0d248
35 changed files with 480 additions and 712 deletions
@@ -15,3 +15,4 @@ code_review: review/code-review.md
 standards_review: review/standards-review.md
 implementation_commit: 9203fdd
 release: v0.0.5
+superseded_by: GOV-009/source-only-deployment-design.md
@@ -22,7 +22,7 @@ repository
 │       ├── http-contracts/      Server DTO
 │       ├── message-contracts/   Server 内部 RocketMQ 信封
 │       └── infrastructure/      Redis、MySQL、消息与生命周期适配
-├── deploy/                      Compose、systemd、Nginx、env 模板
+├── deploy/                      systemd、Nginx、env 源码部署模板
 └── tools/                       治理、Schema、契约、边界和部署验证
 ```

@@ -33,7 +33,7 @@ repository
 3. **一个 Server 工程、三个进程入口。** API、Scheduler、Worker 使用相同基础设施与消息契约，但启动、配置和部署彼此独立。当前规模下没有必要拆成三个仓库或三个重复 Nest 工程；未来可独立扩容进程而不复制公共代码。
 4. **配置是进程级最小权限。** API 不读取任务消费配置，Scheduler 不读取 MySQL/AI 密钥，Worker 不读取 API 端口。配置先校验和冻结，再通过动态模块注入，测试与生产使用同一装配路径。
 5. **基础设施通过 Adapter 隔离。** 业务代码将依赖 MessageBus、Repository 和数据源端口；RocketMQ 客户端尚未验证时明确禁用，避免以临时内存队列形成错误语义。
-6. **部署方式共享同一产物。** Ubuntu 源码部署使用 Web dist 与三个 Server dist 入口；现有 Docker Compose 只作为可选交付适配层复用这些产物，不形成第二套应用逻辑。按用户 2026-08-13 的决定，日常开发不再构建 Docker，待核心功能完成后再决定保留或移除。
+6. **生产只有一条源码路径。** Ubuntu 源码部署直接使用 Web dist 与三个 Server dist 入口，由 systemd 和 Nginx 管理；源码发布门禁验证这些路径一致，避免维护第二套构建和运行语义。

 ## 适合下一阶段的扩展方式

@@ -48,7 +48,7 @@ repository
 - RocketMQ 只有契约和禁用 Adapter，尚未选择并验证 Node 客户端。
 - TypeORM 已固定安全选项，但尚无业务实体和迁移。
 - 用户体系和订阅能力按用户决定后置，不在 GOV-009 范围。
- Docker 交付方式尚未最终确认；现有文件和历史验证保留，但不能据此推定最终生产一定采用容器部署。
+- 仅源码部署调整已实现；历史 Docker 验证只作为决策追溯，不再代表当前可用能力。

 ## 复核结论

@@ -61,7 +61,7 @@ RocketMQ 消息契约属于 Server 的进程间协议，只由 Scheduler 与 Wor

 ## 配置加载

-本地启动固定读取 `deploy/env/development/<process>.env.local`；生产运行依靠 Compose `env_file` 或 systemd `EnvironmentFile` 注入，不从源码目录寻找生产 env。配置解析采用白名单 Schema，未知键可以保留给其他进程，但当前进程只解析最小集合。
+本地启动固定读取 `deploy/env/development/<process>.env.local`；生产运行只依靠 systemd `EnvironmentFile` 注入，不从源码目录寻找生产 env。配置解析采用白名单 Schema，未知键可以保留给其他进程，但当前进程只解析最小集合。

 敏感值只用于建立连接，错误对象和日志使用键名而不输出实际值。Web 构建只加载 `web.env.local` 中的 `VITE_` 变量。

@@ -88,7 +88,8 @@ Server 数据访问使用 Nest 官方 `@nestjs/typeorm` 集成、TypeORM 和 `my
 - Web 使用 Vitest 验证启动外壳和生成客户端边界。
 - Playwright 验证 Web 能启动、路由可访问且无阻断错误；GOV-009 不进行业务页面视觉设计。
 - 使用真实 Redis 和固定开发 MySQL 执行只读冒烟；RocketMQ 只验证禁用态和既有管理链路，不宣称 Node 消息收发通过。
- Web、三个 Server 入口和两个 Dockerfile均执行构建验证。
+- Web 与三个 Server 入口执行真实构建验证；源码发布门禁同时核对 systemd 和 Nginx 模板。
+- E2E 在启动 API 前只读检查现有本机 Redis；不可达时明确失败，不启动替代基础设施。

 ## 回退原则

@@ -96,4 +97,4 @@ GOV-009 不迁移业务数据。回退时恢复上一 Git 标签即可移除脚

 ## 实施后架构论证门禁

-本文档描述的是实施前目标架构。完成代码、测试、构建和 Review 后，必须根据 GitNexus 实际依赖图、Web/Server 目录、三个 Server 进程、OpenAPI 生成链路和部署镜像另写 `architecture-review.md`。复核需要说明实际实现与目标的偏差、当前选择优于替代方案的理由、何时应拆分或调整。用户再次确认前不发布 `v0.0.8`，也不把本功能视为彻底完成。
+本文档描述的是实施前目标架构。完成代码、测试、构建和 Review 后，必须根据 GitNexus 实际依赖图、Web/Server 目录、三个 Server 进程、OpenAPI 生成链路和源码部署产物另写 `architecture-review.md`。复核需要说明实际实现与目标的偏差、当前选择优于替代方案的理由、何时应拆分或调整。用户再次确认前不发布 `v0.0.8`，也不把本功能视为彻底完成。
@@ -15,3 +15,4 @@ release: unreleased
 completion_gate: 实施完成后必须基于实际前后端架构向用户论证并再次确认
 architecture_review: architecture-review.md
 source_only_deployment_design: source-only-deployment-design.md
+source_only_deployment_implementation_plan: source-only-deployment-implementation-plan.md
@@ -32,7 +32,7 @@
 - Server 配置解析、条件必填和启动失败策略。
 - API 健康检查、OpenAPI 产物与 Web 客户端生成链路。
 - Redis 与 MySQL 开发连接健康检查；RocketMQ 保持配置可选和默认关闭。
- 源码构建所需 Dockerfile 与现有生产 Compose 命令对齐。
+- Ubuntu 源码部署所需 Web/Server 产物与 systemd、Nginx 命令对齐，Docker 能力由后续确认的仅源码决策移除。
 - Schema 开发配置路径、固定远程开发库白名单及空库基线处理。

 ## 非目标
@@ -43,6 +43,7 @@
 - 不把 HTTP DTO、数据库实体或消息事件做成前后端共享源码包。
 - 不实现未经验证的 RocketMQ Node SDK；本功能只建立 Adapter 边界、配置校验和禁用态启动能力。
 - 不创建、删除或修改生产基础设施与生产数据。
+- 不管理本地或生产 Redis、MySQL、RocketMQ 的生命周期，不提供容器兜底。

 ## 验收标准

@@ -56,4 +57,5 @@
 - Schema 工具只接受 `development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4_general_ci` 和固定主机白名单；其他远程主机立即拒绝。
 - 空开发库可以生成可验证的 captured Schema 基线，不用空 SQL 冒充结构，也不退回 `not_applicable`。
 - 单元测试、契约测试、构建、开发启动冒烟和适用的浏览器验证全部通过。
+- 仓库不存在活动 Dockerfile、Compose 或 Docker 专用门禁；`pnpm verify:release` 只执行源码发布检查。
 - 全部实施完成后必须基于真实代码和部署产物提交《实施架构复核》，向用户论证前后端职责、依赖方向、进程边界、替代方案和演进成本；获得用户再次确认前，GOV-009 不得标记完成或创建发布标签。
@@ -46,3 +46,22 @@
 - 本机 Redis `127.0.0.1:6379` 的 DB 0、1、2 分别执行只读 `PING`，三次均返回 `PONG`；未读取或修改业务键。
 - 固定开发 MySQL 只读会话返回 `5.7.42-0ubuntu0.18.04.1`、库 `a_share_analysis_dev`、`utf8mb4`、`utf8mb4_general_ci`、会话时区 `+08:00`；Task 1 对象计数为 0。密码只通过临时进程环境传递，未输出或写入命令参数；未连接、探测或读取生产数据库。
 - 本机 RocketMQ 只读 TCP 可达性复核：NameServer `127.0.0.1:9876`、Broker `127.0.0.1:10911`、Proxy `127.0.0.1:8081` 均可达。Node Adapter 仍保持禁用，没有创建 Topic、消费或发送消息。
+
+## 仅源码部署调整（2026-08-13）
+
+### RED
+
+- `pnpm test:deployment` 因 `verify-source-deployment.mjs` 尚不存在而失败，证明新测试先于源码发布门禁实现。
+- `pnpm test:environment-baseline` 因 Docker 活动文件和本地 Compose 指令仍存在而失败，证明政策测试能捕获待移除能力。
+- `node --test server/tools/run-test-api.test.mjs` 因 `checkLocalRedis` 尚未导出而失败，证明外部 Redis 预检行为先有测试。
+
+### GREEN
+
+- 源码部署夹具：5/5；覆盖完整发布、Docker 活动文件、Worker 产物缺失、systemd root 用户和 Nginx 错误配置。
+- 环境与部署契约：10/10；活动 Docker 入口不存在，本地外部 Redis和唯一 Ubuntu 源码部署规则通过。
+- Redis 预检：2/2；OS 分配的本机 TCP 端口分别验证可达和不可达，不安装或启动外部服务。
+- 本机 `redis-cli -h 127.0.0.1 -p 6379 ping` 返回 `PONG`。
+- Server 原有 30 项 Vitest 与新增 2 项 Node 测试全部通过。
+- Playwright 桌面与移动视口共 4/4，通过真实本机 Redis、API 健康接口和 Web 同源代理链路。
+
+前述 `pnpm verify:docker` 及镜像验证内容是调整前的真实历史证据。2026-08-13 用户确认仅源码部署后，这些能力已被取代并从活动仓库删除，不再执行或作为发布依据。
@@ -6,10 +6,11 @@ GOV-009 建立了可运行的应用工程基线：
 - Server 提供 API、Scheduler、Worker 三个独立入口、最小权限配置和优雅关闭生命周期。
 - HTTP 契约由 Server DTO/OpenAPI 单向生成 Web 客户端；RocketMQ 消息契约保持 Server 内部。
 - Redis/MySQL 只读健康检查、TypeORM MySQL 5.7.42 基线和 RocketMQ 禁用 Adapter 已建立。
- 开发/生产模板、Docker Compose、Ubuntu systemd/Nginx 与源码部署路径已对齐。
+- 开发/生产模板、Ubuntu systemd/Nginx 与唯一源码部署路径已对齐。
 - Schema 支持固定远程开发库与真实空库 `captured_empty`，历史清单保持不可变。
- 新增契约漂移、Vue SFC 边界、三进程生命周期、Playwright 真实 API 和 Docker 集成门禁。
+- 新增契约漂移、Vue SFC 边界、三进程生命周期、Playwright 真实 API 和源码发布门禁。
+- 删除 Dockerfile、Compose、镜像校验和容器测试；Redis/MySQL/RocketMQ 统一为外部服务。

 当前状态为 `reviewing/unreleased`。实现提交已推送至 `origin/main`，但按用户要求，必须完成基于真实实现的架构论证并再次确认后才能创建和推送 `v0.0.8` 标签。

-Docker Compose 当前降级为待定的可选交付能力：保留既有文件和历史验证，不进入后续日常开发必跑流程；核心功能完成后由用户决定最终保留 Docker 还是仅采用源码部署。
+2026-08-13 后续确认的仅源码部署决策已取代此前可选 Docker 交付结论。历史验证记录继续保留用于追溯，但仓库不再提供可执行 Docker 能力。
@@ -44,8 +44,10 @@

 ## R7 部署与质量

- Web 与 Server 分别提供可重复构建的 Dockerfile，生产 Compose 使用不可变镜像并与真实产物路径一致。
- 源码部署的 systemd 命令必须与 Server 构建产物一致。
+- 项目只支持 Ubuntu 22.04/24.04 LTS x86_64 源码部署，不提供 Docker 运行、构建、测试或部署入口。
+- Web、API、Scheduler、Worker 构建产物必须完整，源码部署的 systemd 命令必须与三个 Server 构建入口一致。
+- 本地 Redis 和生产 Redis/MySQL/RocketMQ 均为外部系统服务，项目脚本不得安装、启动、停止或删除它们。
+- `verify:release` 必须校验真实构建产物、systemd 最小权限和 Nginx Web/API 链路；Redis 不可达时 E2E 必须明确失败且不得提供容器兜底。
 - 根级检查必须覆盖格式、静态检查、类型、单元测试、契约测试和构建。
 - 所有关键配置边界、契约生成和启动失败行为必须有自动化测试。
 - Server 使用 `@nestjs/swagger` 输出稳定的 `openapi.json`；Web 使用 `openapi-typescript` 与 `openapi-fetch` 生成类型安全客户端。
@@ -10,8 +10,9 @@ GOV-009 没有创建业务表、执行迁移、写入生产数据库、创建 Ro

 ## 部署回退

- Docker 恢复上一组 Web/Server 不可变镜像摘要；源码部署把 `/opt/a-share-analysis/current` 切回上一完整发布目录并重启三个 systemd 服务。
+- 把 `/opt/a-share-analysis/current` 原子切回上一完整发布目录并重启 API、Scheduler、Worker 三个 systemd 服务。
 - `/etc/a-share-analysis/*.env`、本地 `*.env.local`、Redis、MySQL 和 RocketMQ 数据不随应用回退覆盖或删除。
 - 回退后重新执行健康检查、契约门禁和可用性验证。
+- 外部基础设施和 `/etc/a-share-analysis/*.env` 不属于应用回退范围，禁止删除或覆盖。

 当前尚未创建 `v0.0.8` 标签，因此无需删除或移动标签。用户确认发布后，若发布回退也只能新建更高版本修复或明确的回退提交，不能移动已推送标签。
@@ -12,6 +12,8 @@
 - Schema 固定远程白名单、未知远程拒绝和 `api.env.local` 优先级测试。
 - Schema 空库 captured 清单、摘要和历史目录不可覆盖测试。
 - Web、Server 类型检查、单元测试和生产构建。
+- 源码发布门禁检查 Docker 活动入口不存在、四类构建产物完整、systemd 最小权限和 Nginx Web/API 链路。
+- API E2E 的 Redis TCP 预检覆盖可达与不可达，证明失败时不启动替代基础设施。

 ## 真实环境冒烟

@@ -19,10 +21,10 @@
 - 固定开发 MySQL 验证认证、5.7 服务端、数据库名、字符集、排序规则和 `+08:00` 会话时区。
 - RocketMQ 验证 NameServer、Broker 和 Proxy 可达；不创建 Topic，不发送消息。
 - 浏览器访问 Web 与 API 健康检查，无控制台阻断错误。
+- `pnpm verify:release` 只执行源码发布链路，不调用 Docker。

 ## 安全检查

 - Git 跟踪文件不得包含本地密码、开发库凭据、AI Key 或生产地址。
 - Web 构建产物不得包含 Server env 键或消息契约。
 - 连接错误和测试日志不得输出密码。
-