# 开发、生产环境与双部署方式实施计划 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 建立可机器验证的开发/生产环境变量契约、本地 Redis Compose，以及 Docker Compose 与 Ubuntu 源码生产部署规范和配置骨架。 **Architecture:** 八份 env 模板按进程和环境分离，但同一进程在 development/production 使用相同变量名。静态契约测试负责检查模板完整性、敏感值为空、Web 仅暴露 `VITE_*`、生产安全默认值和部署文件边界；当前应用尚未实现，不伪造可运行的应用镜像或启动命令。 **Tech Stack:** dotenv 模板、Docker Compose、Redis、systemd、Nginx、Node.js 内置测试运行器、Markdown、GitNexus。 ## Global Constraints - 环境仅定义 `development` 与 `production`，生产禁止模拟数据、热更新和开发默认值回退。 - 仓库提交八份 `*.env.example`，不提交任何真实 `.env` 或凭据。 - 本地 Compose 只启动 Redis；Web/API/Scheduler/Worker 从源码运行。 - 生产支持 Docker Compose 和 Ubuntu 22.04/24.04 x86_64 源码部署。 - Node.js 22 LTS、pnpm 10、Nginx 和基础设施由管理员提供，项目只验证不安装。 - 源码部署使用 `a-share` 用户和 `/etc/a-share-analysis/*.env`。 - MySQL 与 RabbitMQ 第一阶段默认关闭；MySQL 条件配置遵守 GOV-005。 --- ### Task 1: 建立失败的环境配置契约测试 **Files:** - Create: `tools/governance/environment-baseline.test.mjs` - Modify: `package.json` **Interfaces:** - Consumes: `deploy/env/`、`deploy/compose/`、`deploy/systemd/`、`deploy/nginx/` 和 `docs/deployment/`。 - Produces: `npm run test:environment-baseline`。 - [ ] **Step 1: 编写模板和部署边界测试** 测试八份模板存在、同一进程两环境键集合相同、敏感键为空、Web 仅含 `VITE_*`、生产安全开关正确、本地 Compose 仅定义 Redis，并检查 systemd/Nginx 与两份生产部署文档。 - [ ] **Step 2: 验证测试因文件缺失而失败** 运行：`npm run test:environment-baseline` 预期：失败明确指出第一份缺少的环境模板或部署文件。 ### Task 2: 实现统一环境模板 **Files:** - Create: `deploy/env/development/api.env.example` - Create: `deploy/env/development/scheduler.env.example` - Create: `deploy/env/development/worker.env.example` - Create: `deploy/env/development/web.env.example` - Create: `deploy/env/production/api.env.example` - Create: `deploy/env/production/scheduler.env.example` - Create: `deploy/env/production/worker.env.example` - Create: `deploy/env/production/web.env.example` - Modify: `.gitignore` **Interfaces:** - Consumes: GOV-006 设计中的变量作用域。 - Produces: 后续 NestJS Schema 和部署方式共同使用的变量名契约。 - [ ] **Step 1: 编写四类进程模板** 每项变量附中文说明；敏感变量保持空值；MySQL/RabbitMQ/AI 由功能开关控制条件必填；生产值拒绝模拟数据和调试模式。 - [ ] **Step 2: 加固忽略规则** 只允许提交 `*.env.example`，忽略 `*.env.local`、真实 env 和本地运行目录。 ### Task 3: 实现本地 Redis 与生产部署骨架 **Files:** - Create: `deploy/compose/development.yml` - Create: `deploy/compose/production.yml.example` - Create: `deploy/systemd/a-share-api.service.example` - Create: `deploy/systemd/a-share-scheduler.service.example` - Create: `deploy/systemd/a-share-worker.service.example` - Create: `deploy/nginx/a-share-analysis.conf.example` - Create: `docs/deployment/local-development.md` - Create: `docs/deployment/docker-compose-production.md` - Create: `docs/deployment/ubuntu-source-production.md` **Interfaces:** - Consumes: Task 2 的模板键集合。 - Produces: 本地 Redis 启动入口、生产 Compose 配置边界、systemd EnvironmentFile 和 Nginx 代理示例。 - [ ] **Step 1: 配置本地 Redis Compose** 固定 Redis 镜像补丁版本，只暴露本机端口，使用项目专用容器名、网络、健康检查和仓库外本地数据目录；不得定义其他服务。 - [ ] **Step 2: 配置生产部署骨架** 生产 Compose 只表达应用服务的配置契约和不可变镜像要求；systemd 使用独立 EnvironmentFile，Nginx 托管静态文件并代理 `/api/`。 - [ ] **Step 3: 编写开发与双生产部署文档** 明确当前应用尚未脚手架化，文档只验证配置与部署边界；列出管理员前置条件、版本检查、健康检查、升级和回退规则。 - [ ] **Step 4: 验证测试转绿** 运行：`npm run test:environment-baseline && npm run test:mysql-baseline && npm run test:governance` 预期：全部通过。Docker 可用时额外运行 `docker compose -f deploy/compose/development.yml config`。 ### Task 4: 完成现行规范、追溯与发布 **Files:** - Modify: `docs/architecture/system-architecture.md` - Modify: `docs/governance/code-development-standards.md` - Modify: `docs/governance/development-workflow.md` - Modify: `README.md` - Modify: `docs/index.md` - Modify: `CHANGELOG.md` - Modify: `VERSION` - Create: GOV-006 除现有 `design.md`、`implementation-plan.md`、`gitnexus/before.md` 外的全部必备档案。 **Interfaces:** - Consumes: 通过契约测试的配置与部署文件。 - Produces: 可审查、可发布、可回退的 GOV-006 完整档案和 `v0.0.5`。 - [ ] **Step 1: 更新架构和开发规范** 记录环境模型、配置校验、两种部署方式、平台范围、管理员职责和生产防误用要求。 - [ ] **Step 2: 执行 GitNexus、测试和双 Review** 检测完整暂存区并运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。 - [ ] **Step 3: 中文提交、推送与发布** 提交并推送 `main`；封存后创建带注释 `v0.0.5`，精确推送并核对分支与标签。