部署与流水线

本页说明六个在用项目怎样构建、发布、查日志和回滚。仓库能够确认运行方式和构建命令；云效流水线名称、触发分支和生产账号属于平台配置，交接时必须从云效、Codeup、阿里云函数计算和微信公众平台核实。

发布关系

项目	运行形态	仓库可确认的启动或构建方式	产物或目标
`clientapi`	阿里云 FC3	自定义运行时执行 `python3 app.py`	云函数 `clientapi`
`storeapi`	阿里云 FC3	自定义运行时执行 `python3 app.py --env=prod`	云函数 `storeapi`
`yunapi`	阿里云 FC3	自定义运行时执行 `python3 app.py --env=prod`	云函数 `yunapi`
`clientui`	uni-app H5/微信小程序	`npm run build:h5` 或 `npm run build:mp-weixin`	`dist/build/h5` 或 `dist/build/mp-weixin`
`storeui`	微信小程序	`npm run build:mp-weixin`	`dist/build/mp-weixin`
`yunui`	Vue 2 静态站点	`npm run build:prod`	`dist`，发布到 `/www/wwwroot/yun.jingangai.cn`

sysapi、sysui 已停用，不纳入发布清单。发现旧流水线仍启用时，先确认是否还有生产流量，再决定停用，不能直接删除。

后端云函数发布

三个后端都存在 s.yaml，目标区域为阿里云深圳，运行时为 custom.debian10。s.yaml 证明云函数资源和启动命令，不等同于云效流水线配置。

发布前

确认改动是否包含数据库迁移、环境变量或第三方回调变化。
运行项目相关测试和启动检查。
数据库迁移先评估旧前端兼容、历史数据和回滚 SQL。
storeapi 如与 storeui 同步改造，后端必须兼容微信当前线上旧包。
确认当前提交会触发哪个流水线和生产环境，避免误推测试或历史分支。

发布后

在云效查看本次流水线是否完成构建和部署。
在阿里云函数计算查看对应函数的新版本、实例启动和调用错误。
检查数据库、Redis、OBS 和第三方配置加载是否成功。
验证本次改动涉及的接口，不以健康检查成功代替业务验证。
涉及内部任务时，用 dry-run 或小批量参数验证，不直接全量补跑。

失败日志

阶段	查看位置	重点字段
拉取或构建失败	云效流水线任务日志	仓库、提交号、依赖安装、构建命令、凭据权限
部署失败	云效部署步骤、Serverless 工具输出	函数名、区域、资源权限、版本发布结果
启动失败	阿里云函数计算实例日志	启动命令、模块导入、环境变量、数据库和 Redis 初始化
接口报错	函数调用日志和业务日志	`trace_id`、`request_id`、订单号、门店标识、异常栈
回调异常	函数日志和本地回调记录表	第三方流水号、签名校验、幂等结果、业务状态

回滚

暂停继续发布，记录失败提交、流水线执行号和影响范围。
确认最后一个已验证的提交和数据库兼容情况。
优先用新的回滚提交恢复代码，再通过同一生产流水线发布，保留完整变更记录。
如果生产已配置云函数版本或别名回滚，可切回上一稳定版本；具体入口和权限以生产交接表为准。
数据库、支付、钱包、保险和订单状态不能只靠代码回滚。先确认已产生的数据，再执行补偿或兼容处理。
回滚后重新验证启动、关键接口、任务和第三方回调。

`yunui` 发布

bash

cd yunui
npm run build:prod

构建成功后生成 dist。发布步骤：

保存远端当前版本，备份文件名包含发布时间或提交号。
将 dist 内容打包，通过 SSH/MCP 上传到服务器。
在 /www/wwwroot/yun.jingangai.cn 解压覆盖，不把外层 dist 目录多套一层。
检查远端 index.html 和静态资源目录存在。
打开生产站点验证登录、菜单、接口代理和本次改动页面。
出现问题时恢复上一版静态文件，并清理浏览器或 CDN 缓存后复查。

覆盖远端文件属于生产操作，执行前确认目标路径，不使用未展开的环境变量或宽泛目录。

`storeui` 发布

bash

cd storeui
npm run build:mp-weixin

产物位于 dist/build/mp-weixin。通过微信开发者工具导入该目录，完成真机预览、上传、版本说明、体验版验证和微信审核。审核通过后按约定窗口发布。

小程序不能像静态站点一样即时覆盖。线上问题优先评估后端兼容修复；需要回退小程序时，只能选择微信平台允许回退的已发布版本或重新提审新包。

`clientui` 发布

bash

cd clientui
npm run build:h5
npm run build:mp-weixin

两个命令分别生成 H5 和微信小程序产物。仓库没有证明当前生产 H5 上传目录、域名切换方式和微信发布账号，接手人发布前必须核实生产渠道，不能照搬 storeui 或 yunui 的路径。

知识库 Codeup 仓库

知识库建议从当前大仓库中独立出来，使用单独的私有 Codeup 仓库。仓库只保存 docs-kb 目录里的 VitePress 源码，不保存 node_modules、.vitepress/dist 和发布压缩包。

新建仓库

进入云效代码管理 Codeup，单击“新建代码库”。
选择“普通新建”。现有知识库已有工程文件，不选择 Spring、React 等系统模板，也不使用“模板新建”。
填写以下信息：

配置项	建议值
代码库名称	`jingang-docs-kb`
代码库路径	`jingang-docs-kb`
所属代码组	金刚项目所在代码组；没有时先建 `jingang` 代码组
公开性	私有，仅代码库成员可见
默认分支	`main`
初始化文件	不创建 README、`.gitignore` 和许可证，避免与现有工程产生两套提交历史

创建完成后，从代码库“克隆”入口复制 SSH 地址。开发电脑需要先在 Codeup 个人设置中登记 SSH 公钥。
首次推送完成后，在“设置 > 分支设置”中把 main 设为保护分支。

整理独立仓库

当前知识库位于大仓库的 docs-kb 子目录。首次迁移时，在大仓库之外准备一个新目录，只复制知识库源码：

bash

mkdir -p ../jingang-docs-kb
rsync -a \
  --exclude node_modules \
  --exclude .vitepress/cache \
  --exclude .vitepress/dist \
  --exclude '*.tar.gz' \
  --exclude '*.tgz' \
  docs-kb/ ../jingang-docs-kb/
cd ../jingang-docs-kb
npm ci
npm run docs:build

构建通过后再初始化仓库。将下方地址替换成 Codeup 页面复制的 SSH 地址：

bash

git init
git branch -M main
git add .
git commit -m "初始化金刚项目知识库"
git remote add origin <Codeup-SSH-地址>
git push -u origin main

首次推送前用 git status --short 检查文件。node_modules、.vitepress/dist、压缩包、SSH 私钥、数据库口令和第三方密钥都不能进入提交。

权限和分支规则

角色	建议权限	适用人员
管理员	管理成员、分支规则和流水线关联	项目负责人、技术负责人，至少两人
开发者	建分支、推送、创建合并请求	日常维护知识库的产品、运营和研发
浏览者	读取和克隆，不可推送	只需查阅源码或审计的人员

main 建议禁止直接推送和强制推送，至少一人评审通过后才能合并；未解决的评论不能合并。把知识库构建流水线设为合并卡点，构建未运行或失败时不允许合并。人员离职或职责变化后，当天移除 Codeup、Flow 和服务器权限，并检查个人 SSH 公钥和服务连接。

知识库宝塔手工发布

知识库是 VitePress 静态站点。推荐先构建，再把 .vitepress/dist 的内容打包上传到宝塔；只上传 Markdown 和项目源码不能直接被 Nginx 正常展示。 生产环境不需要长期运行 vitepress dev 或 Node 服务。

本地构建要求 Node.js 20 及以上、npm 10 及以上：

powershell

npm ci
npm run docs:build
Test-Path .vitepress/dist/index.html
tar -a -c -f docs-kb-release.zip -C .vitepress/dist .

不要使用会把 ZIP 内部路径写成 Windows 反斜杠的旧版压缩工具；上传前用 tar -tf docs-kb-release.zip 确认条目路径为 ./assets/... 这类正斜杠路径。

也可以生成 Linux 常用的压缩包：

bash

npm ci
npm run docs:build
test -f .vitepress/dist/index.html
tar -C .vitepress/dist -czf docs-kb-release.tar.gz .

宝塔手工发布步骤：

确认宝塔站点根目录，当前文档约定为 /www/wwwroot/docs.jingangai.cn；实际站点不一致时以宝塔网站配置为准。
先把当前站点目录备份到带日期或提交号的独立目录。
上传 docs-kb-release.zip 或 docs-kb-release.tar.gz，先解压到临时发布目录。
确认临时目录根层直接存在 index.html、assets、jingang 和 handover，不要在站点目录外再套一层 .vitepress/dist。
用临时目录替换站点目录，设置目录属主为 www:www、目录权限为 755、文件权限为 644。
执行 nginx -t，静态文件发布通常不需要重启应用；如修改过 Nginx 配置，再平滑重载 Nginx。
访问首页和本次新增页面，确认返回 200、侧边栏可用、静态资源没有 404。

如果坚持上传源码到服务器，服务器必须安装符合版本要求的 Node.js 和 npm，并在每次发布后执行 npm ci && npm run docs:build，再让 Nginx 指向构建产物。该方式会增加服务器依赖和源码暴露面，不建议作为宝塔生产发布方式。node_modules、.vitepress/cache、旧的 .vitepress/dist 和本地压缩包都不应提交到 Git。

知识库云效 Flow 流水线

建议建立两条流水线，避免普通文档分支直接改动生产站点。

流水线名称	触发方式	用途
`jingang-docs-kb-check`	合并请求新建或更新；可同时监听普通分支代码提交	安装依赖、构建知识库，作为 `main` 合并卡点
`jingang-docs-kb-production`	合并请求完成后，分支过滤为 `main`；保留手工运行入口	重新构建、人工确认、发布到金刚服务器

创建构建检查流水线

进入云效流水线 Flow，在“我的流水线”中单击“新建流水线”。
选择 Node.js 构建模板；如果当前组织没有对应模板，选择自定义流水线。
流水线源选择“代码源 > Codeup”，绑定 jingang-docs-kb 仓库，默认分支选择 main。
开启代码源触发，勾选“合并请求新建/更新”和“代码提交”。普通分支可设为 docs/*；用于合并卡点时要确保每次合并请求更新都会运行。
构建环境选择 Node.js 20，工作目录使用仓库根目录，执行：

bash

set -e
node --version
npm --version
npm ci
npm run docs:build
test -f .vitepress/dist/index.html
test -f .vitepress/dist/handover/index.html

保存并运行一次，在每个任务卡片的“日志”中确认依赖安装、VitePress 构建和文件检查都成功。
回到 Codeup 的 main 保护分支规则，把该流水线加入自动化检查。

创建生产发布流水线

复制构建检查流水线，命名为 jingang-docs-kb-production。
代码源仍使用 jingang-docs-kb，开启“合并请求完成后”触发，并把分支过滤设为 main。
构建任务执行：

bash

set -e
npm ci
npm run docs:build
test -f .vitepress/dist/index.html
test -f .vitepress/dist/handover/index.html
tar -C .vitepress/dist -czf docs-kb-release.tar.gz .
tar -tzf docs-kb-release.tar.gz >/dev/null

添加构建物上传步骤，上传 docs-kb-release.tar.gz，制品名使用 docs-kb-release-${PIPELINE_ID}，保证每次发布可追溯。
在部署阶段前增加人工确认，确认页面至少展示提交号、提交人、构建结果和变更说明。生产发布只允许项目负责人或指定发布人确认。
在 Flow“全局设置 > 主机组管理”新建 jingang-docs-kb-production 主机组，把金刚服务器接入该主机组。Runner 安装命令和 Token 属于敏感凭据，只在云效页面和服务器终端使用，不写进文档或仓库。
添加“主机部署”任务，选择该主机组并勾选下载构建物。让压缩包在部署任务工作目录中保持文件名 docs-kb-release.tar.gz。
部署脚本使用以下内容：

bash

set -euo pipefail

PACKAGE="${PWD}/docs-kb-release.tar.gz"
TARGET="/www/wwwroot/docs.jingangai.cn"
BACKUP_ROOT="/www/wwwroot/_backups"
RELEASE_ID="${PIPELINE_ID:-$(date +%Y%m%d-%H%M%S)}"
STAGE="/www/wwwroot/docs.jingangai.cn.release-${RELEASE_ID}"
BACKUP="${BACKUP_ROOT}/docs.jingangai.cn-${RELEASE_ID}"

test -f "${PACKAGE}"
test -d "${TARGET}"
test ! -e "${STAGE}"
test ! -e "${BACKUP}"
tar -tzf "${PACKAGE}" >/dev/null

install -d -m 755 "${BACKUP_ROOT}"
install -d -m 755 "${STAGE}"
tar -xzf "${PACKAGE}" -C "${STAGE}"
test -f "${STAGE}/index.html"
test -d "${STAGE}/assets"
test -f "${STAGE}/handover/index.html"

restore_on_error() {
  if [ ! -e "${TARGET}" ] && [ -d "${BACKUP}" ]; then
    mv "${BACKUP}" "${TARGET}"
  fi
}
trap restore_on_error ERR

mv "${TARGET}" "${BACKUP}"
mv "${STAGE}" "${TARGET}"
chown -R www:www "${TARGET}"
find "${TARGET}" -type d -exec chmod 755 {} +
find "${TARGET}" -type f -exec chmod 644 {} +
test -f "${TARGET}/index.html"
nginx -t

trap - ERR
printf 'release=%s\nbackup=%s\n' "${TARGET}" "${BACKUP}"

脚本会先校验制品，再解压到独立目录，最后切换站点目录。每次发布的备份路径会打印在部署日志中，不能在同一流水线里自动删除备份。

发布后验证

部署任务后增加验证任务，至少检查首页、交接首页和部署说明：

bash

set -e
curl -fsS https://docs.jingangai.cn/ >/dev/null
curl -fsS https://docs.jingangai.cn/handover/ | grep -q '项目交接'
curl -fsS https://docs.jingangai.cn/handover/deployment-and-pipelines | grep -q '部署与流水线'

验证失败时流水线必须标红，并通知发布人检查 Flow 部署日志、/www/wwwlogs/docs.jingangai.cn.error.log 和本次备份路径。

回滚知识库

先从发布日志复制准确的备份目录，再由有生产权限的人执行。下例中的备份目录必须替换成本次发布日志记录的实际路径：

bash

set -euo pipefail

TARGET="/www/wwwroot/docs.jingangai.cn"
BACKUP="/www/wwwroot/_backups/docs.jingangai.cn-<实际发布编号>"
FAILED="/www/wwwroot/_backups/docs.jingangai.cn-failed-$(date +%Y%m%d-%H%M%S)"

test -d "${TARGET}"
test -f "${BACKUP}/index.html"
test ! -e "${FAILED}"
mv "${TARGET}" "${FAILED}"
mv "${BACKUP}" "${TARGET}"
chown -R www:www "${TARGET}"
nginx -t
curl -fsS https://docs.jingangai.cn/ >/dev/null
printf 'failed_release=%s\nrestored=%s\n' "${FAILED}" "${TARGET}"

回滚只恢复静态文件，不会影响数据库。失败版本仍保存在 FAILED 路径，确认问题和磁盘空间后再由管理员处理。

生产流水线交接表

交接人需要在云效或 Codeup 逐项核对并将结果登记到受控的内部资产台账。知识库保留字段和核实日期，不保存访问密钥。

项目	必须核实的内容
`clientapi`	流水线名称与 URL、触发分支、部署命令、环境、函数版本、日志入口、回滚权限
`storeapi`	流水线名称与 URL、触发分支、自动部署条件、函数版本、日志入口、回滚权限
`yunapi`	流水线名称与 URL、触发分支、自动部署条件、函数版本、日志入口、回滚权限
`clientui`	H5 上传路径、域名/CDN、微信 AppID、上传账号、审核和回滚方式
`storeui`	微信 AppID、开发者工具项目、上传账号、体验成员、审核和发布时间
`yunui`	构建节点 Node 版本、SSH 账号归属、远端目录、备份目录、缓存刷新方式

交接验收

接手人能够找到六个项目的仓库、默认维护分支和发布负责人。
接手人能够在云效找到最近一次成功与失败记录。
接手人能够在函数计算按提交或时间定位日志。
接手人知道谁可以发布、谁只能查看，以及离职后由谁回收权限。
接手人完成一次非生产演练或使用历史版本复盘发布和回滚步骤。

部署与流水线 ​

发布关系 ​

后端云函数发布 ​

发布前 ​

发布后 ​

失败日志 ​

回滚 ​

yunui 发布 ​

storeui 发布 ​

clientui 发布 ​

知识库 Codeup 仓库 ​

新建仓库 ​

整理独立仓库 ​

权限和分支规则 ​

知识库宝塔手工发布 ​

知识库云效 Flow 流水线 ​

创建构建检查流水线 ​

创建生产发布流水线 ​

发布后验证 ​

回滚知识库 ​

生产流水线交接表 ​

交接验收 ​

部署与流水线

发布关系

后端云函数发布

发布前

发布后

失败日志

回滚

`yunui` 发布

`storeui` 发布

`clientui` 发布

知识库 Codeup 仓库

新建仓库

整理独立仓库

权限和分支规则

知识库宝塔手工发布

知识库云效 Flow 流水线

创建构建检查流水线

创建生产发布流水线

发布后验证

回滚知识库

生产流水线交接表

交接验收