部署、升级与维护

当前交付方式

组件	地址	自动化来源与权限
Web	https://yunstack.duruofu.cn/	main推送/手动Actions，公开站点、业务需登录
后端	https://yunstack-s.duruofu.cn/	master推送/手动Actions，健康公开、业务按接口鉴权
文档	https://yunstack-docs.duruofu.com/	Cloudflare Pages，组织账号访问；触发分支在控制台核实
小程序	微信客户端	本机官方miniprogram-ci上传开发版，体验/审核/正式另行操作

这些是测试环境。上述地址与既有部署回执有记录，本次仅静态核对仓库工作流，不重新连接服务器。wrangler.toml指定文档assets目录，但不能据此推断Cloudflare Pages控制台分支。

后端版本目录

部署运行在Linux，Node24、pnpm11.0.8、PM2、flock、tar和curl必须在非交互SSH PATH可见。根目录/root/project/yunstack-backend包含人工维护.env、pm2.config.js、releases/<sha>和current软链接。PM2入口固定current/dist/src/main.js，cwd固定根目录，端口从.env SERVER_PORT_HTTP取得，既有反代为9875；不要把默认Joi端口误当反代实际端口。

Actions先冻结依赖、生成Prisma客户端、单测/HTTP回归和构建，再白名单打包dist/src及运行配置，SCP上传。服务器不拉GitHub源码，安装生产依赖后原子切current、同步PM2配置、reload目标进程，再检查公网HTTPS健康。不会打包/覆盖.env、uploads、数据库或执行迁移。串行部署+flock避免同时切换，成功后保留current、上一个版本和必要新版本，默认共3个可识别Release。

服务器必须已经有有效current；首次初始化不是正常发布脚本职责。新机器由管理员准备.env、首个releases目录、current和PM2注册，确认服务可启动后才开启自动部署。若PM2最初注册的是旧直接dist路径，要一次性修正注册入口；以后只切current即可。不要照历史流程每次delete/start全部应用。

配置自动部署

后端仓库Secrets：SSH_HOST、SSH_USER、SSH_PRIVATE_KEY，可选SSH_PORT；主机公钥固定在workflow，使用StrictHostKeyChecking=yes。服务器重装后通过可信通道核验新公钥再更新，不使用ssh-keyscan临时信任或关闭校验。

开发者提交组件并推送对应分支后，在GitHub Actions看此次SHA的任务；验证必须核对具体SHA，不能只看最近一次绿色任务。以下在服务器只读检查：

readlink -f /root/project/yunstack-backend/current
pm2 describe yunstack-backend
curl -fsS https://yunstack-s.duruofu.cn/api/v1

current应指向本次SHA，PM2 online且入口/cwd正确，健康HTTP200、application/json、code00000。健康只验证基本服务，随后检查登录与MQTT订阅/业务指标。脚本健康最多12次，每次curl上限20秒、间隔5秒，并非固定60秒总超时。

失败与回滚

依赖安装失败不切current；切换、配置同步、reload或健康失败时脚本尝试恢复上一个Release和PM2配置并以非零退出。回滚警告必须人工确认实际进程，不能以workflow退出就认为已恢复。

人工回滚在服务器、持有部署锁、确认目标目录后进行。目标必须是已核验旧Release，不自动选择时间最新目录：

cd /root/project/yunstack-backend
# 在独立维护窗口中持锁；下面旧SHA用实际目录替换
flock .deploy.lock bash
ln -sfn releases/旧的完整提交SHA .current-next
mv -Tf .current-next current
cp current/pm2.config.js pm2.config.js
pm2 reload pm2.config.js --only yunstack-backend --update-env
curl -fsS https://yunstack-s.duruofu.cn/api/v1
exit

这只回退应用，数据库增量不自动撤销，设备固件也不回退。配置变更先检查新旧应用兼容。不要回滚到不认识当前数据结构的应用。

Web、文档与小程序

Web Actions使用Node20/pnpm10，pnpm build包含vue-tsc，上传dist后切换目标目录并检查HTML/应用标识；站点目录在workflow为/opt/1panel/www/sites/yunstack.duruofu.cn/index。只更新静态站点不会升级后端。生产VITE_APP_BASE_API指向远程API，修改环境变量须重新构建。

文档安装锁定依赖、pnpm docs:build产出.vitepress/dist；Cloudflare Pages控制台构建/身份保护由管理员维护。小程序上传见本机开发版上传，Git推送不等于手机体验版已更新。

OSS下载

私有工厂固件目录与OTA目录分离。浏览器登录取得300秒签名URL后直接从OSS下载，再校验原始字节长度/SHA256/芯片容量；大镜像可用gzip透明传输，但哈希基于解压后的镜像。OTA每次通知取得短期HTTPS链接，设备直接下载校验；后端不是二进制代理。

慢在“下载与校验”时检查OSS域名、CORS、签名过期、客户端网络和实际下载耗时，不先归因USB。CORS配置工具yunstack-backend/tools/configure-oss-download-cors.cjs会改桶配置，只有管理员审阅后执行，不在普通排障时自动运行。

本机local-tools的范围

根目录local-tools被Git忽略，包含SSH jdy状态/日志、快速部署、MQTT证书同步辅助、小程序上传SDK和私钥等。新克隆没有这些文件：需维护者从受控本机恢复工具来源、安装依赖、自行设置SSH主机校验和凭据，不能从仓库找不存在的私钥。

快速部署只用于明确授权的在线联调，不能代替组件提交和Actions可追溯发布。仅有源码时使用仓库内Actions作为标准部署入口；不要要求新成员必须先找到某台开发机的local-tools才能理解系统。证书与EMQX维护见专题。未验证的Docker Compose建议不再作为当前推荐部署路径。