Skip to content

部署与流水线 ​

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

发布关系 ​

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

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

后端云函数发布 ​

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

storeapi/s.yaml 中路 AppID 和密钥使用部署环境变量作为可选回退,默认留空;生产按单投保凭据由云平台加密配置读取。不要为了通过部署而写入明文密钥。STANDARD_ORDER_INTERNAL_TOKEN 仍须由部署流水线提供,不能设置为空。

发布前 ​

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

发布后 ​

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

失败日志 ​

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

回滚 ​

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

yunui 发布 ​

bash
cd yunui
npm run build:prod

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

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

新建仓库 ​

  1. 进入云效代码管理 Codeup,单击“新建代码库”。
  2. 选择“普通新建”。现有知识库已有工程文件,不选择 Spring、React 等系统模板,也不使用“模板新建”。
  3. 填写以下信息:
配置项建议值
代码库名称jingang-docs-kb
代码库路径jingang-docs-kb
所属代码组金刚项目所在代码组;没有时先建 jingang 代码组
公开性私有,仅代码库成员可见
默认分支main
初始化文件不创建 README、.gitignore 和许可证,避免与现有工程产生两套提交历史
  1. 创建完成后,从代码库“克隆”入口复制 SSH 地址。开发电脑需要先在 Codeup 个人设置中登记 SSH 公钥。
  2. 首次推送完成后,在“设置 > 分支设置”中把 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 .

宝塔手工发布步骤:

  1. 确认宝塔站点根目录,当前文档约定为 /www/wwwroot/docs.jingangai.cn;实际站点不一致时以宝塔网站配置为准。
  2. 先把当前站点目录备份到带日期或提交号的独立目录。
  3. 上传 docs-kb-release.zip 或 docs-kb-release.tar.gz,先解压到临时发布目录。
  4. 确认临时目录根层直接存在 index.html、assets、jingang 和 handover,不要在站点目录外再套一层 .vitepress/dist。
  5. 用临时目录替换站点目录,设置目录属主为 www:www、目录权限为 755、文件权限为 644。
  6. 执行 nginx -t,静态文件发布通常不需要重启应用;如修改过 Nginx 配置,再平滑重载 Nginx。
  7. 访问首页和本次新增页面,确认返回 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;保留手工运行入口重新构建、人工确认、发布到金刚服务器

创建构建检查流水线 ​

  1. 进入云效流水线 Flow,在“我的流水线”中单击“新建流水线”。
  2. 选择 Node.js 构建模板;如果当前组织没有对应模板,选择自定义流水线。
  3. 流水线源选择“代码源 > Codeup”,绑定 jingang-docs-kb 仓库,默认分支选择 main。
  4. 开启代码源触发,勾选“合并请求新建/更新”和“代码提交”。普通分支可设为 docs/*;用于合并卡点时要确保每次合并请求更新都会运行。
  5. 构建环境选择 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
  1. 保存并运行一次,在每个任务卡片的“日志”中确认依赖安装、VitePress 构建和文件检查都成功。
  2. 回到 Codeup 的 main 保护分支规则,把该流水线加入自动化检查。

创建生产发布流水线 ​

  1. 复制构建检查流水线,命名为 jingang-docs-kb-production。
  2. 代码源仍使用 jingang-docs-kb,开启“合并请求完成后”触发,并把分支过滤设为 main。
  3. 构建任务执行:
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
  1. 添加构建物上传步骤,上传 docs-kb-release.tar.gz,制品名使用 docs-kb-release-${PIPELINE_ID},保证每次发布可追溯。
  2. 在部署阶段前增加人工确认,确认页面至少展示提交号、提交人、构建结果和变更说明。生产发布只允许项目负责人或指定发布人确认。
  3. 在 Flow“全局设置 > 主机组管理”新建 jingang-docs-kb-production 主机组,把金刚服务器接入该主机组。Runner 安装命令和 Token 属于敏感凭据,只在云效页面和服务器终端使用,不写进文档或仓库。
  4. 添加“主机部署”任务,选择该主机组并勾选下载构建物。让压缩包在部署任务工作目录中保持文件名 docs-kb-release.tar.gz。
  5. 部署脚本使用以下内容:
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、触发分支、自动部署条件、函数版本、日志入口、回滚权限
clientuiH5 上传路径、域名/CDN、微信 AppID、上传账号、审核和回滚方式
storeui微信 AppID、开发者工具项目、上传账号、体验成员、审核和发布时间
yunui构建节点 Node 版本、SSH 账号归属、远端目录、备份目录、缓存刷新方式

交接验收 ​

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

用于金刚项目内部协作、运营培训和客户说明。