deployment

部署与升级

本页说明部署责任和核对顺序，不宣称已经完成生产验收。以版本范围为准；生产后端应在目标 Linux 环境验证。macOS 和 Windows 的本地开发结果不能替代目标运行环境验证。

准备一次可追溯部署

部署前确定宿主 commit、Composer 锁文件、基础包版本、业务插件版本/ZIP 摘要及数据库备份。保存消费方 .env、上传文件、应用覆盖层、server/storage/sandpackage/ 与旧 runtime/sandpackage/。插件存储是持久登记和恢复数据，不是可以清空的缓存；具体保护规则见消费与同步。

先在隔离宿主安装固定依赖，完成零插件登录，再测试插件安装、菜单权限和核心业务路径；升级、卸载按相应版本说明验证。不要拿“包下载成功”替代“数据库和运行代码已安装”。

构建管理前端

在待发布的同一 revision 的 sandadmin-artd/ 中，配置 .env.production；生产示例中 API 前缀为 /prod。使用构建主机已准备好的 Node.js/pnpm：

pnpm install --frozen-lockfile
pnpm run build

两条命令均需成功退出；build 包含 Vite 构建与 vue-tsc --noEmit 类型检查。源码配置输出目录为 dist/。类型检查若失败，不能因为目录已经存在就发布。保留旧产物，按部署系统先构建暂存产物再切换；宿主尚没有可照做的统一安全激活 CLI。

Web 服务器静态根指向已发布产物，为 Vue 页面路由配置入口回退，并配置 HTTPS 和 API 代理。生产 /prod API 前缀应剥离后转发至后端，例如 /prod/core/login → /core/login。具体服务器配置取决于站点域名、端口和子目录；不要把开发 Vite 代理当作生产代理。

后端进程与运行目录

在 server/ 安装锁定的 Composer 依赖并运行 composer check-platform-reqs。确保进程用户可写必要的运行日志、上传目录及插件持久存储；初始化时安装器还需要写 .env 与数据库配置。避免为排障把整个站点设为全员可写。

Unix 前台启动入口为 php start.php start；生产应由自己的进程管理系统运行固定目录的该入口。更新进程前保留日志和当前版本记录，按站点既有维护窗口完成停旧、切换和启动新版本；涉及 SQL 时按对应升级说明单独执行并记录结果。

确认部署结果

1. 记录后端实际运行目录和 revision，核对基础包锁定版本。
2. 访问实际 HTTPS 站点，登录后查看系统菜单、用户信息和一个插件页面。
3. 检查 API 返回内容及日志；HTTP 200 不保证业务返回成功。
4. 核对实际提供的前端产物属于本次构建，避免旧浏览器缓存或旧静态根。
5. 按业务插件 README 检查权限、配置与核心路径，再记录业务结果。

源码复制、构建完成、静态切换和页面验证是不同结果，详见前端载荷契约。

升级失败时

未执行 SQL 前可按保存的版本回退代码和产物；已执行 SQL 后仅回退代码不能恢复数据库，须按已验证的备份恢复流程处理。遇到未知提交结果、旧异常登记或缺失插件文件时，保留现场，见排障及生命周期适配。不手改状态或重跑安装 SQL。

来源：进程入口配置、构建脚本、静态输出与代理。