dpl/docs/maintenance/DEPLOYMENT.md

# 发布与恢复

## 目标与连接

本项目生产站点为 https://dp-link.net，后台 /dove；后端目录 /www/wwwroot/dp-link.net，服务器逻辑名 site-jp02。通过既定白色跳板连接；具体连接资料参见本机 /Users/hellcat/Documents/CoDocs/项目关系.md 与 vps连接资料.md，不把它们的内容提交到公开仓库。

本地 http://dpl.loc/dove 已配置到当前 Laravel public/。本机 Nginx 配置 /usr/local/etc/nginx/servers/dpl.loc.conf，PHP-FPM 使用现有 9000 端口。系统级服务重载可能需要 Mac 管理员授权；不持久保存系统密码。

## Git 发布顺序

1. 复核最新用户要求、目标服务器、仓库和改动范围；读取本地与线上 git status、当前 HEAD、远端。线上既有无关修改必须保留，不能直接 reset --hard、clean 或无范围 stash。
2. 做相关测试和 diff 审查。高影响变更应接受独立审查；不要把未执行的审查记成已通过。确认无凭据、备份、私密配置和其他任务内容混入。
3. 提交所需代码并推送项目 origin；记录明确提交版本。单独前台仓库或其他项目独立处理。
4. 生产先记录当前提交，备份受影响文件/配置；数据库迁移前备份数据库并设计数据恢复方案。验证备份存在与权限，不能只写“有备份”。
5. 按现场状态暂停必要任务，避免本地/线上重复处理同一个邮箱。服务器 git fetch 后更新到明确目标提交，优先 fast-forward，保留无关修改。
6. 如涉及后台资源，初始化仓库指定子模块：git submodule update --init --checkout public/assets/admin。不要擅自升级至上游最新版本。此前缺失子模块曾造成后台 HTML 200 但脚本 404、整页空白。
7. 依赖或数据库变化才执行对应 composer/迁移步骤；不得顺带升级 PHP 或全部系统包。处理 Laravel 配置/视图缓存，重载受影响常驻进程，恢复原调度。
8. 核对线上 HEAD、相关文件、资源 HTTP 状态、页面显示、实际登录/保存、队列及必要的业务闭环。明确尚未到时或未验证的定时任务。

默认发布禁止打包覆盖，除非用户明确指定。服务器直接读取已有仓库优先；不能为了拉取 Git 自动复制本机用户名密码到服务器。凭据传输若被审批拒绝，报告真实原因，使用不涉及该凭据的既有合法读取方式。

## 当前运行依赖

生产使用 php8.4-fpm.service、dpl-horizon.service、Redis 与既有 /etc/cron.d/dpl-scheduler。Horizon 处理 send_email 队列；cron 执行 Laravel schedule:run。mail:poll-inbox 每分钟，mail:reconcile 每五分钟，邮件日报 08:00 加五分钟补偿扫描。时间和锁的实际实现以 Console\Kernel 和服务代码为准。

IMAP 扩展需同时在 CLI 与处理后台请求的 FPM 中可用；安装后不能只验证 CLI，常驻进程可能仍加载旧环境。

## 恢复与排错

- 代码：核对受影响范围和线上未提交修改，再更新到记录的旧提交并恢复缓存/进程。不要为了回滚本任务破坏其他修改。
- 数据：代码回滚不等于数据库回滚。新增业务表与已发送记录通常应保留；删表或恢复整库会损失上线后的数据，需单独决策。
- 账号与配置：使用受保护备份恢复指定字段，保持 APP_KEY。不得跨环境盲目复制加密密钥。
- 后台空白：先查引用的 JS/CSS 和 manifest/子模块，再查浏览器报错；必须实际渲染和登录验收。
- 配置保存失败：检查请求校验、旧配置合并、密钥留空保留、FPM 扩展加载与 Redis 缓存。
- 邮件异常：先查看记录状态、幂等键、配额、收件游标和队列；不能通过重复发真实邮件来试错。

最近备份目录记录为 /root/codex-backups/dpl/，具体任务子目录与版本文件需现场核验；生产受保护备份不纳入 Git。历史 codex/output 中脚本仅作审计，不能不检查幂等和适用版本就重跑。