qipai/docs/deployment-changelog.md

部署变更记录

2026-06-22 / M06-A-mqtt-foundation

• 关联模块：M06-A/IOT-001
• 关联 commit：c140613
• 变化内容：菜单 3 从只读检查扩展为管理员确认后安装/更新 EMQX；新增正式厂商 Topic ACL；后端接入 MQTT.js 3.1/QoS 1、重连、订阅恢复与健康检查。
• 配置变化：新增 MQTT Client ID、重连间隔、连接超时和消息大小环境变量；生产必须配置成对的 MQTT 用户名与密码。
• 数据库变化：无。
• 兼容性：健康接口只新增检查字段；未配置 MQTT 凭据的开发/测试环境不启动连接，生产环境缺凭据会拒绝启动。
• 已执行验证：Windows 全量回归、WSL Bash 语法、WSL EMQX 5.8.9 服务级检查通过；认证冒烟因本地账号缺失按预期 SKIP。
• 回滚方式：回退工程 commit，并恢复旧 ACL 模板；生产若已应用配置，先备份 EMQX 数据和配置后再回滚。
• 生产环境人工步骤：在 101.42.38.246 执行菜单 3，创建 qipai_backend_prod 和设备账号，应用 ACL，限制 18083，执行备份和三个 Topic 冒烟。

2026-06-16 / V5.0-status-doc-guard

• 关联模块：M00-B/SCM-001
• 关联 commit：ef0edda
• 变化内容：新增 scripts/dev/windows/check-status-docs.ps1，校验状态文档中的 V5.0 允许状态枚举，并拦截 本地 HEAD、待推送后回填、待推送后远端校验 等临时占位；接入 test-all.ps1。
• 配置变化：无。
• 数据库变化：无。
• 兼容性：仅增加本地提交前检查，不影响生产菜单或部署脚本。
• 已执行验证：待提交前执行 Windows 总检查和状态文档检查。
• 回滚方式：移除状态文档检查脚本及 test-all.ps1 调用即可回到上一状态。
• 生产环境人工步骤：无。

2026-06-16 / V5.0-release-manifest-dry-run

• 关联模块：M00-E/OPS-003
• 关联 commit：59d92c0
• 变化内容：scripts/setup/deploy-business.sh 新增 --dry-run，可在不写入 /opt/apps 的情况下输出当前 HEAD 的 release manifest JSON；新增 scripts/dev/windows/check-release-manifest.ps1 并接入 test-all.ps1。
• 配置变化：无。
• 数据库变化：无。
• 兼容性：不改变生产菜单 2 的写入行为；dry-run 仅用于 Windows/WSL 本地结构验证。
• 已执行验证：待提交前执行 Windows 总检查、release manifest dry-run 检查和 WSL Bash 语法检查。
• 回滚方式：移除 dry-run 分支和 Windows 检查脚本即可回到上一状态；不涉及生产配置。
• 生产环境人工步骤：无；真实发布清单仍需管理员在生产 Ubuntu 菜单 2 执行后生成。

2026-06-16 / V5.0-wsl-emqx-helpers

• 关联模块：M00-C/WSL-001/IOT-001
• 关联 commit：a690e85
• 变化内容：补齐 scripts/dev/wsl/check-emqx.sh、start-emqx.sh、stop-emqx.sh 三个 WSL 本地 EMQX 辅助入口；check-emqx.sh 复用服务级 MQTT 基线检查。
• 配置变化：无；脚本只操作 WSL 本地 systemd 服务，不安装、不降级、不重置 EMQX。
• 数据库变化：无。
• 兼容性：不影响生产 Ubuntu 菜单，不修改 setup.sh，不触发生产部署。
• 已执行验证：待提交前执行 bash -n scripts/dev/wsl/*.sh、check-emqx.sh、Windows 总检查和敏感信息检查。
• 回滚方式：移除新增三个 WSL 辅助脚本即可回到上一状态；不涉及生产配置。
• 生产环境人工步骤：无；生产 EMQX 仍通过 Ubuntu /opt/apps/setup.sh 菜单和部署文档管理。

2026-06-16 / V5.0-baseline-local-mqtt

• 关联模块：M00-C/M00-E/IOT-001
• 关联 commit：289b64d
• 变化内容：接入 V5.0.md，恢复 V4.8.md 历史备份，新增 docs/current-baseline.md、docs/local-dev-mqtt.md 和 scripts/dev/wsl/check-local-mqtt.sh。
• 配置变化：记录 WSL 本地 EMQX 5.8.9、MQTTX CLI 1.13.0、五个监听端口和 systemd active/enabled 状态。
• 数据库变化：无。
• 兼容性：不重新安装、不降级、不重置 EMQX；只做服务级核验。
• 已执行验证：WSL 本地 MQTT 服务级核验通过；协议认证、ACL、TLS、遗嘱和幂等尚未覆盖。
• 回滚方式：保留 V4.8.md 可追溯；若 V5.0 需回退，应先提交状态说明，不得静默删除 V5.0。
• 生产环境人工步骤：无；本轮不触发生产部署。

2026-06-15 / 0.1.4-m00-backup-check

• 关联模块：M00-E/OPS-004
• 关联 commit：292ab7f
• 变化内容：新增 deploy/backup/backup-policy.template.json、deploy/backup/backup-restore-runbook.md 和 setup.sh --backup-status；备份脚本扩展为检查 MySQL/EMQX/上传文件备份工具、目录和模板。
• 配置变化：初始化目录新增 /opt/apps/uploads；菜单第 6 项继续只写 manifest，不导出真实数据。
• 数据库变化：无。
• 兼容性：仅增加检查、模板和 runbook，不自动执行 mysqldump、emqx ctl data export 或文件归档。
• 已执行验证：Windows 本地检查和敏感信息扫描通过；WSL bash -n、setup.sh --backup-status、setup.sh --preflight/--status/--diagnose 通过，/opt/apps/backups/* 未初始化按预期返回 WARN。
• 回滚方式：移除新增备份模板和 --backup-status 检查即可回到 0.1.3 行为；未改动生产环境。
• 生产环境人工步骤：管理员确认数据库凭据、上传目录、EMQX 配置和保留周期后，再启用真实备份任务。

2026-06-15 / 0.1.3-m00-emqx-check

• 关联模块：M00-E/IOT-001
• 关联 commit：86f7da2
• 变化内容：新增 scripts/setup/emqx.sh、deploy/emqx/install-ubuntu24-amd64.md、deploy/emqx/acl.conf.template 和 deploy/emqx/authorization.hocon.template，菜单第 3 项扩展为 EMQX 服务、端口和模板检查。
• 配置变化：新增 setup.sh --mqtt 非交互检查入口；部署版本升级为 0.1.3-m00-emqx-check。
• 数据库变化：无。
• 兼容性：仅增加检查和模板，不自动安装 EMQX，不写入 /etc/emqx。
• 已执行验证：Windows 本地检查和敏感信息扫描通过；WSL bash -n、setup.sh --preflight/--status/--mqtt/--diagnose 通过，EMQX 未安装和端口未监听按预期返回 WARN。
• 回滚方式：移除新增 EMQX 检查脚本和模板即可回到 0.1.2 行为；未改动生产环境。
• 生产环境人工步骤：管理员按 deploy/emqx/install-ubuntu24-amd64.md 安装 EMQX、应用 ACL 和授权模板，并限制 18083 访问范围。

2026-06-15 / 0.1.2-m00-certbot-check

• 关联模块：M00-E
• 关联 commit：4cb3ab6
• 变化内容：新增 scripts/setup/certbot.sh 和 deploy/certbot/api.txyundm.cn.commands.md，菜单第 4 项追加 Certbot、证书文件、续期配置和 certbot.timer 检查。
• 配置变化：setup.sh --https 会同时输出证书签发命令和续期 dry-run 命令。
• 数据库变化：无。
• 兼容性：仅增加检查和管理员命令说明，不自动申请证书，不写入 /etc/letsencrypt。
• 已执行验证：Windows 本地检查和敏感信息扫描通过；WSL bash -n、setup.sh --preflight/--status/--https/--diagnose、scripts/dev/wsl/check-api-domain.sh 通过，生产项按预期返回 WARN。
• 回滚方式：移除新增 Certbot 检查脚本和命令说明即可回到 0.1.1 行为；未改动生产环境。
• 生产环境人工步骤：管理员在 Ubuntu 上准备 /var/www/certbot、执行 certbot certonly --webroot 和 certbot renew --dry-run。

2026-06-15 / 0.1.1-m00-domain-https-check

• 关联模块：M00-E
• 关联 commit：f5445f1
• 变化内容：新增 deploy/nginx/api.txyundm.cn.conf.template、scripts/setup/domain-https.sh、setup.sh --https 和 Windows 域名检查脚本。
• 配置变化：菜单第 4 项扩展为检查固定域名、Nginx 模板、站点启用状态、TLS 证书和健康端点。
• 数据库变化：无。
• 兼容性：仅增加检查和模板，不自动写入生产 Nginx，不申请证书。
• 已执行验证：Windows 本地检查、敏感信息扫描、PowerShell 解析检查通过；WSL bash -n、setup.sh --preflight/--status/--https/--diagnose 通过，HTTPS 项返回 WARN。
• 回滚方式：移除新增模板和检查脚本即可回到 0.1.0 行为；未改动生产环境。
• 生产环境人工步骤：管理员在 Ubuntu 上安装证书后，按菜单提示复制 Nginx 模板并执行 nginx -t 与 reload。

2026-06-15 / 0.1.0-m00-deploy-baseline

• 关联模块：M00
• 关联 commit：本地 HEAD（push 待完成）
• 变化内容：建立根目录 setup.sh、scripts/setup/*.sh 模块化部署脚本、部署目录和状态文档。
• 配置变化：固定 api.txyundm.cn、/opt/apps、Ubuntu 24.04 amd64。
• 数据库变化：无。
• 兼容性：当前仅菜单骨架，不执行生产改动。
• 已执行验证：Windows 本地检查、WSL bash -n setup.sh scripts/setup/*.sh、setup.sh --preflight、setup.sh --status、setup.sh --diagnose；生产 Ubuntu 未执行。
• 回滚方式：尚未生产部署，无生产回滚。
• 生产环境人工步骤：后续由管理员在 Ubuntu /opt/apps/setup.sh 执行。