CryptPad 2026.5.1 配置参数详解

目标：逐项讲清 CryptPad 2026.5.1 的服务端配置文件（config/config.js）与客户端应用配置（customize/application_config.js）两域参数的含义、官方默认值与实测行为，并给出可直接套用的生产配置模板。全部默认值取自 2026.5.1 官方源码（config/config.example.js、lib/load-config.js、www/common/application_config_internal.js），实测行为均在本机部署的 2026.5.1 实例上验证（实测环境见 《CryptPad 2026.5.1 Docker Compose 部署指南》）。

一、环境信息

• 实例版本：CryptPad 2026.5.1（版本标签 version-2026.5.1，运行时 Node.js v24.16.0）；
• 参数取证文件：config/config.example.js（340 行）、lib/load-config.js（默认值强制逻辑）、config/sso.example.js（SSO 样例）、www/common/application_config_internal.js（客户端 AppConfig 内部默认）；
• 实测验证手段：/api/config 接口实测回显、首启自动生成的 config.js 逐行核对、修改后重启观察行为；
• 部署形态：官方 Compose 方案，配置文件路径 /opt/cryptpad/config/config.js（源码安装对应 <安装目录>/config/config.js，下文统一按此路径书写）。

二、前置条件

1. 已有一套可运行的 CryptPad 2026.5.1 实例（部署见部署指南篇）；
2. 明确两个配置域的分工：服务端行为（域名、端口、存储、配额、日志）改 config/config.js；界面与应用行为（可用应用清单、页脚链接、白板配色）改 customize/application_config.js；两域互不覆盖；
3. 改服务端配置需要重启服务生效；改客户端配置随静态资源下发，重建构建产物后生效（重启服务即可，启动流程每次会重跑前端构建）。

三、参数查看与修改方式

3.1 服务端配置的加载链路（源码实测）

服务端启动时由 lib/load-config.js 加载配置，加载规则实测核对如下：

1. 默认读取 ../config/config.js；环境变量 CRYPTPAD_CONFIG 可指定其他绝对路径；
2. config.js 不存在时回退加载 config/config.example.js 并打印提示：Config not found, loading the example config. You can customize the configuration by copying config/config.example.js to <configPath>；
3. config.js 存在但语法错误时服务直接终止（实测错误文案：config/config.js is faulty. See stacktrace below for more information. Terminating.）；
4. 加载后对关键参数做默认值强制（load-config.js 源码逻辑）：inactiveTime 非正数→90；archiveRetentionTime 非正数→90；maxUploadSize 非正数→20 MB；defaultStorageLimit 非正数→50 MB；premiumUploadSize 非正数或小于 maxUploadSize 时直接删除该键。

⚠️ 注意一个官方注释与代码不一致的点：config.example.js 中 archiveRetentionTime 的注释写「defaults to 15 days」，但 load-config.js 实际强制默认为 90 天。以代码为准：未配置时归档保留 90 天。

3.2 查看当前生效值的三种方法

方法一，/api/config 接口（客户端实际下发的运行时配置，实测回显）：

curl -s http://localhost:8145/api/config

define(function(){;
return {
        "requireConf": {
                "waitSeconds": 600,
                "urlArgs": "ver=2026.5.1-1792616523994"
        },
        "removeDonateButton": false,
        "httpUnsafeOrigin": "http://localhost:8145",
        "adminKeys": [],
        "moderatorKeys": [],
        "inactiveTime": 90,
        "defaultStorageLimit": 52428800,
        "maxUploadSize": 20971520,
        "premiumUploadSize": false,
        "restrictRegistration": false,
        "httpSafeOrigin": "http://127.0.0.1:8145",
        "enableEmbedding": false,
        "listMyInstance": false,
        "sso": false
};
});

方法二，直接读配置文件：grep -vE '^\s*(//|/\*|\*)' /opt/cryptpad/config/config.js | grep -v '^\s*$'； 方法三，管理面板：注册管理员账户后访问 /admin/，配额、注册开关、实例信息等可在界面查看与修改。

3.3 修改方式

服务端：编辑 /opt/cryptpad/config/config.js 后重启服务进程。注意首启自动生成的 config.js 若未持久化，重建部署后会随实例状态一起丢失，生产应把配置目录固定挂载（方法见部署指南篇第八章）。 客户端：cp /opt/cryptpad/customize.dist/application_config.js /opt/cryptpad/customize/application_config.js 后按需修改——这是官方注释推荐的标准做法（源文件注释原文：把 customize.dist/application_config.js 复制到 customize/ 再改）。

四、参数总览

4.1 服务端 config.js 参数一览（默认值来源：config.example.js 与 load-config.js 实查）

4.2 客户端 application_config 参数一览（默认值来源：application_config_internal.js 实查）

五、核心参数分类详解（服务端）

5.1 双域与监听

CryptPad 的安全模型建立在「主域 + 沙箱域」双源之上（架构说明见 《CryptPad 介绍与选型指南》第三章）：

5.2 会话与账户安全

5.3 隐私与合规

logIP（默认 false）：开启后每条 WebSocket 连接记录「连接 ID + 用户公钥 + IP」，官方注释明确该选项用于满足特定司法辖区留日志要求，且要求日志级别为 info 或更低。默认关闭符合 CryptPad「最小化可收集信息」的定位；开启与否应取决于合规义务而非运维习惯。

5.4 管理参数

5.5 存储生命周期

5.6 上传与配额

5.7 数据目录

九个路径参数官方默认值如下（全部相对 CryptPad 安装目录；按部署指南篇部署时这些目录已映射为持久化存储，对照关系见其 5.1 节）：

5.8 日志参数

六、客户端应用配置详解（application_config）

修改入口是 customize/application_config.js（从 customize.dist/ 复制，见 3.3），其内部默认值定义在 www/common/application_config_internal.js。核心项：

6.1 应用可见性三件套

• availablePadTypes（默认含 16 类）：首页「新建」弹窗可展示的应用清单；官方注释要求永远不要从清单移除 drive（否则云盘不可达）；
• registeredOnlyTypes（默认 file/contacts/notifications/support）：仅注册用户可用类型，官方注释同样警告默认项不可随意删（这些功能无账户无法工作）；
• hiddenTypes（默认 10 类）：不进创建弹窗但功能仍存在的类型，默认隐藏了 drive/teams/contacts/todo/file/accounts/calendar/poll/convert。

三者关系实测理解：availablePadTypes 决定「有哪些可创建」，hiddenTypes 决定「哪些不进弹窗」，registeredOnlyTypes 决定「哪些要登录」。例如默认配置下 calendar 可用但藏于独立入口。

6.2 高级与早期访问

• enableEarlyAccess（false）：官方注释说明新应用可能先以「早期访问」状态引入，可能含缺陷甚至导致内容丢失，默认关闭；
• premiumTypes（注释态 ['doc','presentation']）：Word/演示两应用在 2026.5.1 被视为实验性，官方注释原话——默认对用户隐藏，除非经管理面板授予自定义配额，且「此行为不受官方支持，改动后官方不提供帮助」。

6.3 页脚与法务链接

imprint（版权页）、privacy（隐私政策）、terms（服务条款）、roadmap（路线图）、status（状态页）五项默认 false（不显示）；source 默认 true——这是 AGPL 许可的合规项：官方注释要求向所有使用者公开源码，若对平台做过修改，须把该项指向包含修改版源码的仓库地址。三项法务链接均支持三种取值：false（隐藏）、true（用默认页）、对象形式（按语言给 URL，官方注释给出 {"default": ..., "en": ..., "fr": ...} 结构）。

6.4 界面细节

notificationTimeout（5000 ms，通知停留时长）、whiteboardPalette（17 色白板色板，可整组替换）、appBackgroundColor（'#666'，居中内容应用背景）、enableTemplates/enableHistory（模板与历史按钮开关，设 false 即从全部应用移除）、hostDescription（首页社区实例文案，支持按语言配置）、supportLanguages（工单面板管理员语言，示例 ['en','fr']）、surveyURL（官方问卷链接，设 '' 可隐藏）。

七、SSO 配置（可选插件）

2026.5.1 的 SSO 登录通过插件机制提供：lib/env.js 以 plugins?.SSO?.config 读取配置，基础部署形态中 lib/plugins/ 目录实测为空（仅 README），因此 /api/config 实测下发 "sso": false。安装 SSO 插件后按 config/sso.example.js 样例配置，其字段（2026.5.1 实查）：

八、生产配置模板

适用场景：4 GB 内存、NVMe SSD、50 人以内团队的 HTTPS 生产实例（域名以 pad.example.com / 沙箱 pad-sandbox.example.com 为例，替换为实际域名即可）。基于官方 example 全量裁剪，每个取值都可在前文找到依据：

module.exports = {
    // 主域：客户端访问地址，生产必须 HTTPS
    httpUnsafeOrigin: 'https://pad.example.com',
    // 沙箱域：必须与主域不同源（子域即可）
    httpSafeOrigin: 'https://pad-sandbox.example.com',
    // 监听地址与端口（反代转发目标）
    httpAddress: '127.0.0.1',
    httpPort: 3000,
    websocketPort: 3003,

    // 管理面板白名单：值为账户设置页展示的公钥签名串
    adminKeys: [
        "[admin@example.com/YZgXQxKR0Rcb6r6CmxHPdAGLVludrAF2lEnkbx1vVOo=]",
    ],
    // adminEmail: 'admin@example.com',
    restrictRegistration: false,

    // 存储生命周期：90 天未钉住清理；归档保留 15 天；账户闲置 365 天清理
    inactiveTime: 90,
    archiveRetentionTime: 15,
    accountRetentionTime: 365,
    // 如需手动控制清理节奏（配合 scripts/evict-inactive.js）：
    // disableIntegratedEviction: true,

    // 上传与配额
    maxUploadSize: 100 * 1024 * 1024,
    defaultStorageLimit: 500 * 1024 * 1024,

    // 数据目录（默认值，集中列出便于必要时迁移）
    filePath: './datastore/',
    archivePath: './data/archive',
    pinPath: './data/pins',
    taskPath: './data/tasks',
    blockPath: './block',
    blobPath: './blob',
    blobStagingPath: './data/blobstage',
    decreePath: './data/decrees',
    logPath: './data/logs',

    // 日志
    logToStdout: true,
    logLevel: 'info',
    logFeedback: false,
    verbose: false,
};

模板要点解读：httpAddress 收敛到 127.0.0.1 让 node 只听本机回环、由 NGINX 反代对外（官方推荐拓扑）；maxUploadSize/defaultStorageLimit 按团队规模放大，放大上传上限后反代 client_max_body_size 必须同步 ≥ 100M；logToStdout: true 便于接入系统日志采集，磁盘日志仍按 logPath 落盘；archiveRetentionTime: 15 与账户清理按需取舍——保守口径可全部注释掉用代码默认（90/90/365）。

九、常见问题

Q1：改了 config.js 重启后报 config/config.js is faulty？ JS 语法错误，服务拒绝启动（load-config 实测行为：SyntaxError 直接 process.exit(1)）。按日志栈定位行号修正；改前可 node -e "require('/opt/cryptpad/config/config.js')" 预检语法。

Q2：archiveRetentionTime 注释说 15 天，为什么实际是 90 天？ 官方注释与代码不一致：lib/load-config.js 对非正数值强制回退 90。需要 15 天就显式写 archiveRetentionTime: 15（本篇第八、章模板已显式给出）。

Q3：设置了 httpSafeOrigin，3001 端口为什么不监听？ 显式配置沙箱源即为生产模式，沙箱内容由反代把沙箱域转发到主服务端口实现；只有不配置（开发模式）才派生 httpSafePort 监听。详见部署指南篇 4.6 排障实录。

Q4：改 maxUploadSize 后大文件仍上传失败？ 服务端上限放开后还要同步：反代 client_max_body_size ≥ 新上限；且 premiumUploadSize 若小于 maxUploadSize 会被 load-config 静默删除（源码实测）。

Q5：loginSalt 能不能中途加？ 不能。官方注释原文警示：仅可在实例首次创建时设置，事后修改将使全部现有用户无法登录（scrypt 盐与历史凭据不匹配）。

Q6：客户端配置改了不生效？ 确认改的是 customize/application_config.js（而非 customize.dist/ 原件），且文件导出结构未被破坏；重启服务触发重建构建产物后刷新浏览器缓存。

十、参考链接