Admin：增加固定提交构建与安全生产部署脚本 #309

New Issue

2026-08-26T15:42:33+08:00

ila commented

2026-08-26 15:42:33 +08:00

基本信息

类型：需求
父级大工单：#14
所属 MVP / 版本：MVP 后续 / Admin 生产发布自动化
阶段：可重复、安全的生产部署
关联：#81、#303、#307
状态：已完成，待验收

要解决什么

Admin 目前每次发布都由开发者临时组合 Git 导出、Go 交叉编译、上传、备份、独立端口预检、原子切换和回退命令。步骤已经在多次部署工单中验证，但没有仓库内可复用脚本，容易遗漏固定提交构建、凭据排除、后台任务空闲复核或失败回退。

目标是在项目合适目录提供一个可直接运行、面向当前生产环境的部署脚本，把“最新已提交 Admin 代码打包并更新服务器”固化为安全、可审计流程。

做什么 / 不做什么

做什么

在 admin/deploy/ 增加 Windows PowerShell 部署入口和 Linux 远端执行脚本。
默认从当前已提交的 HEAD 建立隔离 Git 归档；工作区未提交文件、config.yaml、业务 Excel 和密钥不得进入产物。
固定使用 Go 1.23.0 执行全量 test、build、vet，再交叉编译 Linux amd64、CGO 关闭的单文件二进制。
使用已有 SSH 密钥或显式 -IdentityFile，不在脚本、参数示例、日志或文档保存密码。
上传后核对 SHA-256，安装到独立 release 目录，复用稳定配置和 data 软链接。
切换前检查生产 schema、四类后台活动任务和服务状态，创建并验证 MySQL gzip 逻辑备份。
在 18083 独立端口使用生产环境预检；通过后再次复核空闲状态，原子切换稳定链接并重启 systemd。
切换或健康检查失败时恢复上一二进制链接并重启。
目标 schema 高于生产时默认停止，只有显式 -AllowSchemaMigration 才允许备份后预检迁移。
增加脚本语法/安全边界测试和简明使用文档。

不做什么

本工单不实际部署生产，也不执行生产 schema v31。
不把 SSH、MySQL、AI、顺运宝或其他凭据写进仓库。
不复制或替换生产 config.yaml、环境文件、AI 密钥和 data/。
不触发顺运宝同步、目录导入、AI 调用、采集、采购、下单或付款。
不自动清理旧 release 或旧备份。
不支持任意服务器拓扑；默认值针对当前 185.216.248.75:21638、systemd 和 /opt/cmautobuy，必要参数可以显式覆盖。

怎么做

admin/deploy/deploy-admin.ps1
- 校验 Git、Go、ssh、scp、目标参数和固定提交；
- 从固定提交导出完整隔离源码并告知工作区脏文件不会被打包；
- 以 Go 1.23.0 验证并生成 Linux amd64 二进制；
- 上传二进制和远端执行器，传递非敏感发布参数；
- 使用 PowerShell ShouldProcess 提供高风险确认和 -WhatIf；
- 精确清理本机临时目录和远端临时上传文件。
admin/deploy/deploy-admin-remote.sh
- 严格校验参数、root 身份、所需路径和命令；
- 通过服务器本机受限配置读取数据库，不输出凭据；
- 校验 schema 与显式迁移授权，检查活动任务；
- 创建并验证单事务 gzip 备份；
- 安装 release、建立稳定配置/data 软链接；
- 18083 预检后原子切换，验证 systemd、Nginx、本机和公网 HTTP；
- 失败时恢复上一稳定链接。
admin/deploy/README.md 记录最短命令、参数、输出、回退和安全边界。
增加自动化测试，至少验证 PowerShell/Bash 语法、固定提交隔离构建、无凭据硬编码、schema 授权门禁、备份/预检/原子切换/回退关键步骤存在。

预计修改：

admin/deploy/deploy-admin.ps1
admin/deploy/deploy-admin-remote.sh
admin/deploy/README.md
admin/deploy_script_test.go
docs/admin/06-quality-security.md
docs/task/309-admin生产部署脚本.md

数据库结构：不改。
Admin/Client HTTP 接口：不改。

验收标准

默认发布当前已提交 HEAD，工作区未提交文件不会进入构建产物。
Go 1.23.0 全量 test、build、vet 成功后才构建 Linux amd64 二进制。
脚本和文档不包含任何密码、Token、Cookie 或私钥内容。
SSH 地址、端口、用户、密钥和公网 URL 可通过参数覆盖，默认适配当前服务器。
上传、本地/远端 SHA-256、独立 release、稳定配置/data 链接均有校验。
切换前完成四类后台任务空闲检查和可验证 MySQL 备份。
schema 升级默认被阻止，只有显式授权才可在备份后由预检启动执行。
18083 预检、二次空闲复核、原子切换、systemd/Nginx/HTTP 健康检查完整。
切换后失败能够恢复上一稳定二进制链接；不删除旧 release 和备份。
-WhatIf 不上传、不备份、不重启服务器。
PowerShell 和 Bash 语法检查、自动化测试、Go 1.23.0 全量测试通过。
完成提交、本地归档和工单实施记录。

怎么验证

从仓库根目录执行：

$errors = $null
[System.Management.Automation.Language.Parser]::ParseFile(
  (Resolve-Path .\admin\deploy\deploy-admin.ps1),
  [ref]$null,
  [ref]$errors
) | Out-Null
if ($errors.Count -gt 0) { throw ($errors | Out-String) }

bash -n ./admin/deploy/deploy-admin-remote.sh
.\admin\deploy\deploy-admin.ps1 -WhatIf

Set-Location admin
$env:GOTOOLCHAIN = "go1.23.0"
go test ./... -count=1
go build ./...
go vet ./...
Remove-Item Env:GOTOOLCHAIN

不在自动化测试中连接生产、创建备份、迁移或重启服务。

风险和回退

部署会重启生产 Admin。控制：PowerShell 高风险确认、后台任务两次检查、独立端口预检和原子链接切换。
数据库迁移可能使旧二进制不兼容。控制：默认禁止 schema 升级；显式授权前先备份，保留旧 release，并在归档中记录迁移后的应用回退边界。
SSH/网络中断可能留下上传文件或未启用 release。控制：使用唯一临时路径、幂等 release 安装和精确清理；未通过预检绝不切换。
公网健康检查可能因短暂网络问题失败。控制：有界重试；切换后仍失败则自动恢复上一链接。
回退：脚本自动恢复切换前稳定二进制；数据库备份只记录并保留，不自动恢复，避免覆盖发布后业务数据。

实施记录（2026-08-26）

实现提交：c6f9a80；归档提交：95954d4。
新增 admin/deploy/deploy-admin.ps1、deploy-admin-remote.sh、使用说明和静态安全测试。
PowerShell AST、Bash -n、-WhatIf、Go 1.23.0 全量 test/build/vet 全部通过。
使用不可连接的本机端口完整验证固定提交 c6f9a80 的隔离导出、Go 1.23.0 测试和 Linux amd64 构建；按预期在首次上传处停止，本次临时目录已清理。
生产只进行了不输出凭据的只读前置核对；没有运行远端部署执行器，没有备份、迁移、切换、重启或触发业务操作。
未验证：真实 18083 预检、schema v31 生产迁移、原子切换和自动回退；本机没有 ShellCheck。
当前状态：代码、文档、测试、归档和推送已完成，等待用户验收。

## 基本信息 - 类型：需求 - 父级大工单：#14 - 所属 MVP / 版本：MVP 后续 / Admin 生产发布自动化 - 阶段：可重复、安全的生产部署 - 关联：#81、#303、#307 - 状态：已完成，待验收 ## 要解决什么 Admin 目前每次发布都由开发者临时组合 Git 导出、Go 交叉编译、上传、备份、独立端口预检、原子切换和回退命令。步骤已经在多次部署工单中验证，但没有仓库内可复用脚本，容易遗漏固定提交构建、凭据排除、后台任务空闲复核或失败回退。目标是在项目合适目录提供一个可直接运行、面向当前生产环境的部署脚本，把“最新已提交 Admin 代码打包并更新服务器”固化为安全、可审计流程。 ## 做什么 / 不做什么 ### 做什么 - 在 `admin/deploy/` 增加 Windows PowerShell 部署入口和 Linux 远端执行脚本。 - 默认从当前已提交的 `HEAD` 建立隔离 Git 归档；工作区未提交文件、`config.yaml`、业务 Excel 和密钥不得进入产物。 - 固定使用 Go 1.23.0 执行全量 test、build、vet，再交叉编译 Linux amd64、CGO 关闭的单文件二进制。 - 使用已有 SSH 密钥或显式 `-IdentityFile`，不在脚本、参数示例、日志或文档保存密码。 - 上传后核对 SHA-256，安装到独立 release 目录，复用稳定配置和 data 软链接。 - 切换前检查生产 schema、四类后台活动任务和服务状态，创建并验证 MySQL gzip 逻辑备份。 - 在 18083 独立端口使用生产环境预检；通过后再次复核空闲状态，原子切换稳定链接并重启 systemd。 - 切换或健康检查失败时恢复上一二进制链接并重启。 - 目标 schema 高于生产时默认停止，只有显式 `-AllowSchemaMigration` 才允许备份后预检迁移。 - 增加脚本语法/安全边界测试和简明使用文档。 ### 不做什么 - 本工单不实际部署生产，也不执行生产 schema v31。 - 不把 SSH、MySQL、AI、顺运宝或其他凭据写进仓库。 - 不复制或替换生产 `config.yaml`、环境文件、AI 密钥和 `data/`。 - 不触发顺运宝同步、目录导入、AI 调用、采集、采购、下单或付款。 - 不自动清理旧 release 或旧备份。 - 不支持任意服务器拓扑；默认值针对当前 `185.216.248.75:21638`、systemd 和 `/opt/cmautobuy`，必要参数可以显式覆盖。 ## 怎么做 1. `admin/deploy/deploy-admin.ps1` - 校验 Git、Go、ssh、scp、目标参数和固定提交； - 从固定提交导出完整隔离源码并告知工作区脏文件不会被打包； - 以 Go 1.23.0 验证并生成 Linux amd64 二进制； - 上传二进制和远端执行器，传递非敏感发布参数； - 使用 PowerShell `ShouldProcess` 提供高风险确认和 `-WhatIf`； - 精确清理本机临时目录和远端临时上传文件。 2. `admin/deploy/deploy-admin-remote.sh` - 严格校验参数、root 身份、所需路径和命令； - 通过服务器本机受限配置读取数据库，不输出凭据； - 校验 schema 与显式迁移授权，检查活动任务； - 创建并验证单事务 gzip 备份； - 安装 release、建立稳定配置/data 软链接； - 18083 预检后原子切换，验证 systemd、Nginx、本机和公网 HTTP； - 失败时恢复上一稳定链接。 3. `admin/deploy/README.md` 记录最短命令、参数、输出、回退和安全边界。 4. 增加自动化测试，至少验证 PowerShell/Bash 语法、固定提交隔离构建、无凭据硬编码、schema 授权门禁、备份/预检/原子切换/回退关键步骤存在。预计修改： - `admin/deploy/deploy-admin.ps1` - `admin/deploy/deploy-admin-remote.sh` - `admin/deploy/README.md` - `admin/deploy_script_test.go` - `docs/admin/06-quality-security.md` - `docs/task/309-admin生产部署脚本.md` 数据库结构：不改。 Admin/Client HTTP 接口：不改。 ## 验收标准 - [x] 默认发布当前已提交 HEAD，工作区未提交文件不会进入构建产物。 - [x] Go 1.23.0 全量 test、build、vet 成功后才构建 Linux amd64 二进制。 - [x] 脚本和文档不包含任何密码、Token、Cookie 或私钥内容。 - [x] SSH 地址、端口、用户、密钥和公网 URL 可通过参数覆盖，默认适配当前服务器。 - [x] 上传、本地/远端 SHA-256、独立 release、稳定配置/data 链接均有校验。 - [x] 切换前完成四类后台任务空闲检查和可验证 MySQL 备份。 - [x] schema 升级默认被阻止，只有显式授权才可在备份后由预检启动执行。 - [x] 18083 预检、二次空闲复核、原子切换、systemd/Nginx/HTTP 健康检查完整。 - [x] 切换后失败能够恢复上一稳定二进制链接；不删除旧 release 和备份。 - [x] `-WhatIf` 不上传、不备份、不重启服务器。 - [x] PowerShell 和 Bash 语法检查、自动化测试、Go 1.23.0 全量测试通过。 - [x] 完成提交、本地归档和工单实施记录。 ## 怎么验证从仓库根目录执行： ```powershell $errors = $null [System.Management.Automation.Language.Parser]::ParseFile( (Resolve-Path .\admin\deploy\deploy-admin.ps1), [ref]$null, [ref]$errors ) | Out-Null if ($errors.Count -gt 0) { throw ($errors | Out-String) } bash -n ./admin/deploy/deploy-admin-remote.sh .\admin\deploy\deploy-admin.ps1 -WhatIf Set-Location admin $env:GOTOOLCHAIN = "go1.23.0" go test ./... -count=1 go build ./... go vet ./... Remove-Item Env:GOTOOLCHAIN ``` 不在自动化测试中连接生产、创建备份、迁移或重启服务。 ## 风险和回退 - 部署会重启生产 Admin。控制：PowerShell 高风险确认、后台任务两次检查、独立端口预检和原子链接切换。 - 数据库迁移可能使旧二进制不兼容。控制：默认禁止 schema 升级；显式授权前先备份，保留旧 release，并在归档中记录迁移后的应用回退边界。 - SSH/网络中断可能留下上传文件或未启用 release。控制：使用唯一临时路径、幂等 release 安装和精确清理；未通过预检绝不切换。 - 公网健康检查可能因短暂网络问题失败。控制：有界重试；切换后仍失败则自动恢复上一链接。 - 回退：脚本自动恢复切换前稳定二进制；数据库备份只记录并保留，不自动恢复，避免覆盖发布后业务数据。 ## 实施记录（2026-08-26） - 实现提交：`c6f9a80`；归档提交：`95954d4`。 - 新增 `admin/deploy/deploy-admin.ps1`、`deploy-admin-remote.sh`、使用说明和静态安全测试。 - PowerShell AST、Bash `-n`、`-WhatIf`、Go 1.23.0 全量 test/build/vet 全部通过。 - 使用不可连接的本机端口完整验证固定提交 `c6f9a80` 的隔离导出、Go 1.23.0 测试和 Linux amd64 构建；按预期在首次上传处停止，本次临时目录已清理。 - 生产只进行了不输出凭据的只读前置核对；没有运行远端部署执行器，没有备份、迁移、切换、重启或触发业务操作。 - 未验证：真实 18083 预检、schema v31 生产迁移、原子切换和自动回退；本机没有 ShellCheck。 - 当前状态：代码、文档、测试、归档和推送已完成，等待用户验收。

ila referenced this issue

2026-08-26 15:42:41 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue from a commit

2026-08-26 15:52:55 +08:00

feat: 增加 Admin 安全生产部署脚本 (#309)

ila referenced this issue from a commit

2026-08-26 15:52:55 +08:00

docs: 归档任务 #309

ila referenced this issue

2026-08-26 16:26:21 +08:00

建立 Admin 部署与运维长期 Wiki 文档 #316