Table of Contents
Admin 部署与运维
本页用途
本页供 cmautobuy 内部维护者部署和运维生产 Admin。日常发布以仓库 admin/deploy/deploy-admin.ps1 为唯一入口；本页解释它的安全门禁、预期结果和人工停止位置，不另造一套会漂移的手工发布流程。
安全边界
- 部署会连接生产服务器、备份 MySQL、安装 release、重启 systemd 并改变公网服务；只有用户明确要求部署时才能执行。
- 本页只记录配置名称和安全来源，不记录真实密码、Token、Cookie、私钥或证书内容。
- 默认禁止 schema 升级；只有确认迁移和回退兼容性后显式使用
-AllowSchemaMigration。 - 脚本可以在切换失败时恢复上一稳定二进制，但数据库迁移不会自动反向恢复。
- 恢复数据库备份会覆盖备份后的业务数据，必须停止服务、确认影响并由负责人单独授权。
- 发布脚本不会触发顺运宝同步、目录导入、AI 调用、采集、采购、下单或付款。
服务概览
| 项目 | 当前值 |
|---|---|
| systemd 服务 | cmautobuy-admin |
| 运行账号 | cmautobuy:cmautobuy |
| 工作目录 | /opt/cmautobuy |
| 稳定二进制 | /opt/cmautobuy/cmautobuy-admin，指向 release |
| release 目录 | /opt/cmautobuy/releases/<提交短号>/ |
| 稳定配置 | /opt/cmautobuy/config.yaml |
| 稳定数据目录 | /opt/cmautobuy/data/ |
| 环境文件 | /etc/cmautobuy/admin.env，权限受控 |
| AI 密钥目录 | /etc/cmautobuy/secrets/ |
| 内部监听 | 127.0.0.1:18080 |
| 预检监听 | 127.0.0.1:18083，临时 |
| 公网入口 | https://buy.833729.com，由 nginx 反向代理 |
| 数据库 | MySQL 8.4，数据库 autobuy |
| 备份目录 | /opt/cmautobuy/backups/ |
systemd 单元模板在 admin/deploy/cmautobuy-admin.service。服务只监听本机地址，不把 18080/18083 直接暴露到公网。
环境要求
Windows 构建机
从仓库根目录检查：
git --version
go version
tar --version
ssh -V
scp
预期这些命令均存在。部署脚本会强制使用 Go 1.23.0，运行 Admin 全量 test、build、vet，再交叉构建 linux/amd64、CGO_ENABLED=0 单文件。
Linux 服务器
远端执行器要求 bash、sha256sum、mysql、mysqldump、gzip、curl、systemctl、ss、runuser、install、readlink 和 nginx。缺少任一命令都会在修改生产前停止。
只读检查：
systemctl is-enabled cmautobuy-admin
systemctl is-active cmautobuy-admin
nginx -t
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18080/
预期：systemd 已启用且 active；nginx 配置测试成功；Admin 根路径返回 303。
配置与凭据来源
| 名称 | 用途 | 安全来源 | 敏感 |
|---|---|---|---|
CMAUTOBUY_DB_HOST / PORT / NAME / USER |
MySQL 连接定位 | /etc/cmautobuy/admin.env |
部分 |
CMAUTOBUY_DB_PASSWORD |
MySQL 业务账号密码 | 同一权限受控环境文件 | 是 |
CMAUTOBUY_DB_TLS_MODE / TLS_CA |
MySQL TLS 验证 | 环境文件和服务器 CA 路径 | CA 路径否，内容不写入本页 |
CMAUTOBUY_CATALOG_SOURCE |
商品目录来源名 | 环境文件 | 否 |
CMAUTOBUY_CATALOG_TOKEN |
商品目录接口认证 | 环境文件 | 是 |
CMAUTOBUY_AI_SECRETS_PATH |
AI 密钥文件目录 | /etc/cmautobuy/secrets/ |
路径否，内容是 |
CMAUTOBUY_AI_ALLOWED_HOSTS |
AI 服务允许主机 | 环境文件 | 否 |
| MySQL 管理 defaults 文件 | 部署备份和 schema 只读检查 | 服务器 root 专用受控文件 | 是 |
| SSH 私钥 | 生产 SSH 认证 | 维护者本机受控路径或 ssh-agent | 是 |
脚本使用 BatchMode=yes 和严格主机密钥检查，不接收或保存 SSH 密码。
首次部署
首次准备 systemd、nginx、运行账号、目录、环境文件、TLS CA 和数据库权限属于独立运维变更，不能用日常发布脚本替代。最少要完成：
- 创建
cmautobuy系统账号及/opt/cmautobuy、/etc/cmautobuy必要目录。 - 将受控配置和环境文件按最小权限放置，真实值不进入 Git。
- 安装并启用
cmautobuy-admin.service，确认内部只监听127.0.0.1:18080。 - 配置 nginx 和 HTTPS，
nginx -t通过后才 reload。 - 建立 MySQL 8.4 数据库、业务账号、TLS 与备份管理配置。
- 先用独立测试库验证当前 schema，再对生产执行有明确授权的首次迁移。
- 运行本文“健康检查”。
首次部署涉及生产权限和数据，必须有独立工单、回退方案和实际运维确认。
日常发布
1. 只读预览
从仓库根目录：
.\admin\deploy\deploy-admin.ps1 -WhatIf
预期只显示固定提交、目标服务器和是否允许迁移；不构建、不上传、不备份、不重启。
2. 发布无 schema 变化的版本
.\admin\deploy\deploy-admin.ps1 -Commit <已提交的完整哈希或可解析引用>
脚本只使用 git archive <固定提交> 的内容。工作区可以有无关未提交修改，但不会进入发布物；需要发布的新代码必须先提交并推送。
3. 发布含 schema 迁移的版本
当前 2026-08-26 代码声明 MySQL schema v31。生产低于目标版本时，普通发布会在修改前停止并提示目标版本。确认 v31 迁移、自检、旧二进制兼容性和备份恢复代价后，显式执行：
.\admin\deploy\deploy-admin.ps1 -Commit <目标提交> -AllowSchemaMigration
-AllowSchemaMigration 只允许新 release 在备份完成后、18083 独立端口预检时执行仓库中已有迁移；它不跳过 schema 自检，也不授权恢复备份。
固定安全步骤
- 解析并记录 40 位 Git 提交和目标 schema。
- 在隔离源码上用 Go 1.23.0 执行 test、build、vet。
- 构建 Linux amd64 二进制并计算 SHA-256。
- 上传到随机
/tmp路径，服务器核对 SHA。 - 检查当前 systemd、schema 和四类后台活动任务。
- 创建 MySQL 单事务 gzip 备份并检查 gzip、建表语句和 SHA-256。
- 安装到新 release，只链接稳定配置和数据。
- 在
127.0.0.1:18083启动预检，核对根路径、登录页、目标 schema 和后台空闲。 - 原子切换稳定二进制并重启 systemd。
- 核对稳定链接、systemd、nginx、本机 18080、公网根路径和登录页。
任一步失败都不能宣称部署成功。
健康检查与日志
每次发布或回退后：
systemctl is-active cmautobuy-admin
readlink -f /opt/cmautobuy/cmautobuy-admin
nginx -t
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18080/
curl -sS -o /dev/null -w '%{http_code}\n' https://buy.833729.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://buy.833729.com/login
journalctl -u cmautobuy-admin -n 100 --no-pager
预期：服务 active；稳定链接指向目标 release；nginx 测试通过；根路径返回 303；登录页返回 200；日志没有新的致命错误。
schema 和后台任务核对使用服务器本机受控 MySQL 管理配置执行，不把命令输出中的业务数据复制到工单或文档。
数据库迁移、备份与恢复
部署前备份写入 /opt/cmautobuy/backups/autobuy-before-<release>-<UTC时间>-notablespaces.sql.gz，权限 0600。脚本验证：
- gzip 可完整解压；
- 备份至少包含一条
CREATE TABLE； - 记录 SHA-256；
- 使用
--single-transaction --routines --triggers --no-tablespaces。
脚本不会删除历史 release 和备份。
恢复备份不是日常自动回退步骤。需要恢复时必须先停止 Admin，确认将丢失的备份后数据，保存当前故障库证据，在独立环境演练恢复和 schema 自检，再由负责人授权生产恢复。恢复后重新执行登录、schema、任务关系和关键业务数量核对。
回退
- 切换后 systemd、本机 18080、nginx 或公网健康检查失败时，远端执行器会把稳定链接恢复到上一可执行 release 并重启服务。
- 自动回退只处理二进制链接，不恢复数据库。
- 如果新版本已经把 schema 从 v30 升到 v31，只有确认上一二进制兼容 v31 时才能继续使用自动代码回退；不兼容时停止发布并走人工数据库恢复决策。
- 手工回退前先记录当前 release、上一 release、当前 schema、备份路径与 SHA，不删除故障 release。
- 回退后必须重新执行健康检查，未全部通过时立即人工处理。
已知限制
- 当前为单机 systemd 部署，没有灰度、多实例滚动发布。
- #309 的脚本已完成本地语法、测试、隔离构建和失败上传路径验证；截至其验收记录，尚未在该脚本下实际演练生产备份、18083 预检、v31 迁移、原子切换和自动回退。
- 数据库备份恢复不会自动执行，也尚未作为日常脚本能力提供。
- 本页不代替生产变更工单和用户明确部署授权。