企业官网建设流程全解析

• 协同办公
• 后端
• 前端
• 密码学

本文以 CryptPad 仓库根目录下的 CHANGELOG.md 为核心素材，系统梳理该项目从1.29.0到2026.5.1的版本演进脉络、按季节（Spring/Summer/Autumn/Winter）组织的日历化发布节奏，以及每一代版本为实例管理员提供的完整升级步骤、配置参数与反向代理注意事项。读者将掌握 CryptPad 的版本号规则、依赖管理方式（npm ci/npm run install:components/./install-onlyoffice.sh）、数据归档与清理策略（inactiveTime、archiveRetentionTime、accountRetentionTime），以及升级后如何通过/checkup/页面自检实例健康状态。

版本号的两种纪元：从字母代号到日历化发布

CHANGELOG 记录了 CryptPad 两套截然不同的版本命名体系，理解这一点是阅读其余内容的前提。

3.x / 4.x 时代的字母代号周期

在 2024 年之前，CryptPad 采用语义化版本（semver）外加"按字母命名"的双轨体系：

• 2.0 周期（v2.0.0 起）：按字母 A 到 Z 为每个版本取一个可爱的动物名，例如 Alpaca（v2.0.0）、Badger（v2.1.0）、Coati（v2.2.0）、Donkey（v2.3.0）、Echidna（v2.4.0）、Fossa（v2.5.0）、Gibbon（v2.6.0）……
• 3.0 周期（v3.0.0 起）：因为 2.0 周期把字母用完了，改用"已灭绝动物"为主题，例如 Aurochs（v3.0.0）、Baiji（v3.1.0）、Chilihueque（v3.2.0）、Dodo（v3.3.0）……直到 ZyzomysPedunculatus（v3.25.0）。
• 4.0 周期（v4.0.0 起）：重新按字母走，从 A（4.0.0）开始，每次小版本升级按字母顺序推进，约每三周一个版本。
• 5.0 及之后：v5.0.0 ~ v5.7.0 阶段仍保留 semver，但已开始向日历化版本过渡。

这些动物代号之间还穿插了不少xxx's revenge（复仇）之类的补丁版，例如 Thylacine's revenge（3.19.1）、UplandMoa's revenge（3.20.1）、XerusDaamsi's revenge（3.23.1），通常用于快速修复主版本上线后暴露的问题。

2024.3.0 起切换为日历化版本（CalVer）

自2024.3.0起，项目正式放弃 semver，改用 CalVer 风格的YYYY.MM.micro格式，并建立了一套固定的季度发布节奏（原文明确写出）：

• 💐 Spring2024.3.0
• 🌻 Summer2024.6.0（6 月底）
• 🍁 Autumn2024.9.0（9 月底）
• ❄️ Winter2024.12.0（12 月底）

此后每个季度发布的版本号直接对应其月份，例如2025.3.0（Spring）、2025.6.0（Summer）、2025.9.0（Autumn）、2026.2.0（Winter）……一旦发现线上问题，团队会在两次主版本之间发布带 🩹 图标的修复版（fix release），如2026.2.1、2026.2.2、2026.5.1。

从 CHANGELOG 顶部到 2026.5.1，仓库当前已演进到Spring fix release (2026.5.1)，这也应该是当前仓库package.json所对应的版本。升级时以 git tag 为准，例如git checkout 2026.5.1。

升级的标准流程：停止、拉取、装依赖、重启、自检

CHANGELOG 中几乎每个版本都附带一段"Upgrade notes"，其核心步骤高度一致，可归纳为一条可复用的标准升级路径。下面以最新版本2026.5.1的官方说明为准（CHANGELOG.md 顶部）：

1. 停止你的服务器（Stop your server）
2. 用 git 获取最新代码（Get the latest code with git）

git fetch --depth 1 origin tag 2026.5.1 git checkout 2026.5.1 npm ci npm run install:components

3. 重启服务器（Restart your server）
4. 检查实例的 checkup 页面（Review your instance's checkup page to ensure that you are passing all tests）

与旧版本的差异：bower 时代 vs npm 时代

CHANGELOG 记录了客户端依赖管理方式的迁移，升级命令因此发生过多次变化：

• 早期版本（v2.x / v3.x）使用bower update安装客户端依赖、npm install或npm update安装服务端依赖。
• v5.4.0 起移除了 Bower：改为npm install（或如今推荐的npm ci）加npm run install:components，并提示旧目录www/bower_components可以被删除。这个命令对应 package.json 中的"install:components": "node scripts/copy-components.js"，其作用是把 npm 安装的组件拷贝到前端可服务的位置。
• 涉及 OnlyOffice 的版本（如2024.3.0、2024.6.0、2024.9.0、2025.3.0、2025.6.0、2026.2.0、2026.5.0）在升级步骤中还额外包含一句./install-onlyoffice.sh，用于单独安装/更新 OnlyOffice 应用（详见后文）。

升级的连续性要求

CHANGELOG 反复强调一条规则：如果你的实例版本比某版本更旧，需要按顺序阅读两者之间所有版本的升级说明。例如2026.5.0的说明写道："If you are upgrading from a version older than2026.2.2please read the upgrade notes of all versions between yours and2026.5.0to avoid configuration issues."。原因在于部分版本包含破坏性变更（Nginx 配置、配置项移除、数据迁移），跳级升级极易漏掉关键步骤。

升级后验证：/checkup/ 自诊断页面

每个版本的升级步骤都以"检查/checkup/页面"收尾。CHANGELOG 中多次提到该页面的演进：

• 早期是"非常基础的状态"，逐步扩展为检测实例配置错误的自动化测试集合；
• 错误按严重程度排序（Errors 排在 Warnings 之前），并按测试编号排序；
• 针对 CSP 头、WebSocket、/upload-blob、注册开放状态、HSTS 头等都有对应测试；
• 测试会对公共资源只请求一次并缓存，25 秒超时，还包含对浏览器端 API 的检测（如 SharedArrayBuffer）。

版本演进中的关键里程碑

CHANGELOG 实质上是一部按时间顺序排列的功能史，以下是几个对理解 CryptPad 架构至关重要的节点：

核心配置参数解读（结合仓库源码）

CHANGELOG 在多个版本中直接引用 config/config.example.js 中的配置项，以下结合源码注释逐一说明其含义与默认值。

安全相关的域名配置：httpUnsafeOrigin 与 httpSafeOrigin

CHANGELOG（尤其 4.14.0 的 breaking change 说明）反复强调 CryptPad 双域名架构：用户访问的主域名（httpUnsafeOrigin）负责密钥管理等敏感操作，而沙箱域名（httpSafeOrigin）加载大部分 UI，即使沙箱被攻破也无法接触账户密钥。

在 config/config.example.js 中：

• httpUnsafeOrigin: 'http://localhost:3000'——客户端输入地址栏加载实例的 URL；
• httpSafeOrigin——沙箱域名，必须与 httpUnsafeOrigin 不同（源码注释明确要求）；
• 4.14.0 起，若实例从非配置的 origin 加载、或沙箱未正确阻止eval、或浏览器不支持 CSP，CryptPad 会直接拒绝运行（abort），这是从"建议"到"强制执行"的转变。

数据保留与归档：inactiveTime / archiveRetentionTime / accountRetentionTime / disableIntegratedEviction

CHANGELOG 在 3.23.0 一节集中介绍了自动数据库维护机制，对应 lib/eviction.js 的实现。四个核心参数（config/config.example.js 中均以注释形式给出默认值）：

• inactiveTime（默认 90 天）：文档在多少天未被访问后被判定为"不活跃"。服务端会定期扫描数据库，将未存放在任何已注册用户驱动器中的不活跃文档移入归档目录。
• archiveRetentionTime（默认 15 天）：归档文件在被永久删除前保留的天数。
• accountRetentionTime（默认 365 天）：账户多久未活动（未新增文档、已有文档未被他人访问/修改）即被视为不活跃、可被删除。
• disableIntegratedEviction（默认false，即开启集成）：从 3.23.0 起，原本需要 cron 手动执行的node ./scripts/evict-inactive.js被直接集成进服务端，每天自动运行一次；管理员若希望手动控制，可设为true关闭集成。

从 lib/eviction.js 源码可见其行为：retentionTime = +new Date() - (Env.archiveRetentionTime * 24 * 3600 * 1000)；未配置archiveRetentionTime时直接跳过归档清理（第 83 行）；inactiveTime未配置或非数字时同样跳过扫描（第 229 行）；accountRetentionTime若未配置或小于等于 0，则不会删除任何账户（PRESERVE_INACTIVE_ACCOUNTS）。

运维建议（源自 CHANGELOG 原文的提醒）：首次启用集成 eviction 前，务必仔细核对上述数值，避免"突然且无意地删除数据"。

存储配额与上传限制：premiumUploadSize / defaultStorageLimit

• premiumUploadSize（config/config.example.js 中示例100 * 1024 * 1024，即 100MB）：为 premium 用户（CryptPad.fr 的付费用户，或其他实例上customLimits中配置的用户）设置更高的单文件上传上限。
• 3.23.0 起，默认存储配额（原 50MB）与个别用户配额都可以在管理面板的User storage区域调整，且管理面板中设置的配额优先于配置文件中的customLimits。

服务器性能：maxWorkers

CHANGELOG 在 3.16.0 一节说明：服务端子进程过多曾造成线程压力，管理员可通过maxWorkers: <number>限制子进程数量（建议为可用核心数减一）。config/config.example.js 中保留了// maxWorkers: 4,的示例。

OnlyOffice 的安装与升级：install-onlyoffice.sh

从2024.3.0起，OnlyOffice 应用（Sheet、Document、Presentation）不再随主仓库打包，改为独立模块，避免在代码仓库中携带编译产物与历史版本（原文提到旧方式会让实例被迫下载约 1.7GB 用不到的 OnlyOffice 历史版本）。升级 OnlyOffice 需要执行仓库根目录的脚本：

./install-onlyoffice.sh # press q to close the license screen # and Y ⏎ to accept the OnlyOffice license

后续 CHANGELOG 还记录了该脚本自身的演进：

• 2025.3.0为脚本增加了--check、--rdfind、--no-rdfind选项；
• 2026.2.0修复了install-onlyoffice.sh的--check与新install_version函数的兼容问题；
• 2025.3.1特别提示：OnlyOffice 8.3 体积显著增大，安装时需额外约830MB 磁盘空间；
• 2026.5.0将 OnlyOffice 从 8.x 升级到 Drawio/OnlyOffice 相关依赖，其中chainpad-server从^5.2.4升级到^5.3.0，drawio-npm从21.8.2+6升级到29.6.7+3。

另外，2025.3.0说明中提到可选的 SharedWorker 重建步骤：npm run api（对应 package.json 中的"api": "rollup -c"）会重新构建www/common/worker.bundle.min.js（包含 Shared Worker 全部代码的单一构建产物）。注意构建需要安装 npm 开发依赖（不要使用--production标志）。

反向代理（Nginx）配置要点

CHANGELOG 中几乎每个大版本都会附带 Nginx 配置变更说明，比较重要的包括：

WebSocket 限流（2026.2.1）

修复版2026.2.1为高级 Nginx 示例配置增加了速率限制。在 docs/example-advanced.nginx.conf 中可以看到具体实现：

limit_req_zone $binary_remote_addr zone=wslimit:20m rate=30r/m; # ... location ^~ /cryptpad_websocket { limit_req zone=wslimit burst=5 nodelay; limit_req_status 429; }

.mjs 类型支持与 pdfjs（5.7.0）

5.7.0 的升级说明给出了完整的 Nginx diff，核心两点：

1. 在 server 块中加入include mime.types;
2. 新增types { application/javascript mjs; }，为 pdfjs 使用的.mjs文件提供正确的 MIME 类型；同时移除了旧 draw.io 的 CSP script hash 例外。

blob/block 代理（5.5.0）

5.5.0 要求把/blob/与/block/请求代理到 API 服务器，并在示例配置的location ~ ^/(blob|block)/.*$中新增两条指令：

proxy_hide_header 'Cross-Origin-Resource-Policy'; proxy_hide_header 'Cross-Origin-Embedder-Policy';

同时更新了 draw.io 内联脚本的 CSP hash（'sha256-dLMFD7ijAw6AVaqecS7kbPcFFzkxQ+yeZSsKpOdLxps='）。

/api/ 全量转发（5.0.0）

5.0.0 引入/api/instance端点后，Nginx 规则从location ~ ^/api/(config|broadcast).*$扩展为location ~ ^/api/.*$，将全部/api/请求转发给 API 服务器。CHANGELOG 同时提醒：即使暂未更新代理配置，客户端也会回退到合理的默认值，但 checkup 页面会标记该问题，建议尽快修正。

CSP 与沙箱（4.14.0 / 4.13.0）

4.14.0 起 CryptPad 在代码层面强制校验 CSP：沙箱必须阻止eval、实例必须从匹配httpUnsafeOrigin的源加载、默认禁止第三方 iframe 嵌入（除非管理面板显式开启）。4.13.0 则收紧为"仅允许 HTTPS 白名单域名"，且 checkup 页面新增多项严格测试。

Systemd 服务文件调整（5.6.0 / 5.3.0）

5.6.0 要求向cryptpad.service添加日志相关配置（docs/cryptpad.service）：

# Proper logging to journald StandardOutput=journal StandardError=journal+console

并执行sudo systemctl daemon-reload。5.3.0 则移除了过时的日志指令，增加了沙箱与加固最佳实践。

常见升级陷阱与故障排查（来自 CHANGELOG 的实战记录）

CHANGELOG 不只是一份功能清单，还记录了大量真实运维问题，值得实例管理员留意：

• 缓存导致的头信息错乱（3.23.1/3.23.2）：升级顺序错误会使旧版 HTTP 头被缓存并分发到客户端，引发加载失败。3.23.2 专门针对 CKEditor 与 OnlyOffice 的缓存机制做了"强制刷新"，并建议客户端忽略错误缓存。
• Safari/iOS 与浏览器 API 兼容性：多处修复提及 Apple 引擎不支持 SharedWorker、SharedArrayBuffer 等 API，导致共享文件夹、XLSX 导出等在 iOS 上不可用；checkup 页面会提示这类"预期中的失败"。
• git fetch的两种写法：早期版本建议git fetch origin --tags（拉取全部 tag），近期版本改为git fetch --depth 1 origin tag <版本>（浅拉取单 tag），注意按对应版本的说明执行。
• 升级前先看 checkup：4.14.0 的说明建议在升级前先检查 checkup 页面，因为 4.13.0 的测试已能识别绝大多数会导致升级后无法加载的配置问题。
• SSO 插件需同步升级：2025.9.0起明确要求 SSO 插件升级到兼容版本（0.4.0），2026.5.0要求升级到 0.5.0，2026.5.1则修复了 SSO 插件（v0.6.0）相关问题；2025.9.0还新增了forceRedirect到 SSO。使用 SSO 的实例务必与 CryptPad 版本同步升级插件。

结语：把 CHANGELOG 当作运维手册使用

对 CryptPad 实例管理员而言，CHANGELOG.md 的价值远不止"看看新增了什么"：它内含每个版本的完整升级命令、破坏性变更提示、Nginx/Systemd 配置 diff、配置参数语义与默认值，以及 config/config.example.js、docs/example-advanced.nginx.conf、lib/eviction.js、scripts/ 等文件对应的运维细节。建议每次升级按"读 CHANGELOG → 逐版本应用配置变更 → 停止服务 →git fetch --depth 1 origin tag <版本>→npm ci→npm run install:components（必要时./install-onlyoffice.sh）→ 重启 → 检查/checkup/"的顺序执行，即可最大程度避免跳级升级带来的配置漂移与数据风险。

• 协同办公
• 后端
• 前端
• 密码学