发版与后期维护

两条发布路线，先分清你是哪一边

• 发证方（产品的作者）：你改的是程序本身，要把它发布出去，让别人的站能升级。
• 站长（用这套程序建站的人）：你改的是内容与模板，需要把代码升级到新版本。

下面按这两条线分别讲。两边的界面是分开的：发证方在 「发行·发证方」分区，站长在「系统 → 在线更新」。

发证方：发布一个新版本

1. 先改代码，本地能跑通。不要直接改服务器上的文件 —— 那样下一次有人升级，改动会被更新包覆盖掉。
2. 进「版本管理」发布：填版本号、更新说明、上传代码包。 发布是不可撤回的：发布出去之后所有站点的更新列表里都会出现它。
3. 更新说明要写给站长看：这一版改了什么、有没有需要他做的事 （比如要重新配置某个开关）。站长是靠这段文字决定要不要升的。

升级时到底发生了什么

站长的「在线更新」按这个顺序走，中途任何一步失败都会停下并报出来：

1. 校验安装包（签名与哈希），不通过直接拒绝。
2. 先整站备份到 storage/backup/，改动过的文件也留一份。
3. 替换文件。少数几个「内核闸门」文件是原子替换的， 不存在"换了一半"的中间状态 —— 那正是会让站点当场停摆的状态。
4. 清理模板与页面缓存。
5. 跑数据库迁移（Migrate.php）。 ⚠️ 这一步必须在文件替换之后：跑在替换之前的话，用的还是旧代码的步骤表， 等于新版本的迁移从未执行。
6. 同步开发手册章节（见下一节）。这一步失败不算更新失败 —— 文件都已经换好了，把它报成失败只会让人以为站点停在半路。

开发手册章节怎么送到客户站

手册的事实来源是程序目录里的 docs/docs_seed.php， 它在安装那一刻被播种进数据库。所以你在新版里加了章节之后， 客户站要拿到它，只有两条路：

• 在线更新（推荐）：更新流程的最后一步会自动同步，站长什么都不用做。
• 命令行补一次：

  cd 站点根/wwwroot
  php install.php --cli --seed-docs

  只同步手册，别的一律不碰 —— 不动表结构、不重播示例数据、不重置任何开关。 重复执行是安全的（幂等）：已经存在的篇目只在正文变化时才更新。

同步的规则是按 slug 对齐：缺的插入、正文变了的更新、一样的跳过。 ⚠️ 这意味着手工在数据库里改过的正文会被下一次同步覆盖回来， 因为种子文件是唯一事实来源。要长期保住的改动，应该改种子文件本身。

出问题怎么退回去

• 文件：每次更新前的整站备份在 storage/backup/，按时间命名， 可以直接解包覆盖回去。
• 数据库：迁移只做「加表加列」，不删列也不删表， 所以退回旧版代码不会因为"少了列"而报错；新加的表留在库里不碍事。
• ⚠️ 覆盖回去之后要清一次缓存，否则页面还是旧的。

几个必须避开的坑