CryptPad 2026.5.1 Docker Compose 部署指南

在 Ubuntu 22.04 上以官方 cryptpad/cryptpad:version-2026.5.1 镜像从零部署 CryptPad：数据卷属主与沙箱源排障实录、OnlyOffice 三件套安装、持久化验证、升级与运维命令全量实测。

CryptPadCryptPad协作编辑在线办公2026/10/22

CryptPad 2026.5.1 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用官方 cryptpad/cryptpad 镜像与 Docker Compose 从零部署一套可用的 CryptPad 端到端加密协作平台，覆盖部署、数据持久化、OnlyOffice 三件套扩展、升级与排障。本文全部命令与回显均在 Ubuntu 22.04.4 LTS（x86_64，Docker 29.8.1 / Compose v5.5.1）上实测通过，服务版本为官方镜像 version-2026.5.1（写作时点镜像仓库最新版，实查日期 2026-10-22）。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS（Jammy Jellyfish），x86_64；
  • Docker Engine：29.8.1；Docker Compose：v5.5.1（docker compose 子命令形态）；
  • CryptPad 镜像：cryptpad/cryptpad:version-2026.5.1（镜像摘要 sha256:1f89dcdd28c1375f675e47b1d0cf07a51f3e9a07a79dc93c8cddb3295b98a34d，基础系统 Alpine Linux，内置 Node.js v24.16.0）；
  • 服务端口规划：宿主机 8145 → 主域 HTTP（容器内 3000），宿主机 8147 → WebSocket（容器内 3003）；
  • 部署目录：/opt/cryptpad/（Compose 项目根，全部数据卷落在此目录下）；
  • 访问域名（本篇实测形态）：主域 http://localhost:8145、沙箱域 http://127.0.0.1:8145（本机验证用双源方案，生产域名替换方法见第七章）。

💡 说明：为什么沙箱域用 127.0.0.1:8145 而主域用 localhost:8145——CryptPad 要求沙箱源与主域不同源（协议/主机/端口任一不同即可），本机验证没有第二个域名时，localhost 与 127.0.0.1 恰好构成两个不同源。实测验证：两者均返回 HTTP 200 且 /api/config 正确下发双源（见第四章）。

二、镜像选型说明

候选镜像结论依据（2026-10-22 实查）
cryptpad/cryptpad:version-2026.5.1本文采用官方 Docker Hub 组织发布、与 GitHub 源码 tag 对应、版本可固定
cryptpad/cryptpad:latest可用但不推荐生产官方 compose 默认值，浮tag不可复现；写作时点 latest 即 2026.5.1
opendesk-2026.08.04 等变体标签不采用面向 openDesk 集成场景的定制构建，非通用部署
自行源码构建备选官方文档主线为源码安装，适合需要深度定制的场景

版本背景（实查日期 2026-10-22）：GitHub 源码最新 Release 为 2026.10.0（2026-10-21 发布），但 Docker Hub 尚无对应镜像标签（version-2026.10.0 返回 404），镜像仓库最新可用版本标签即 version-2026.5.1（2026-05-26 更新）。镜像更新通常滞后源码数周，部署以镜像仓库实际可拉取的版本标签为准。

官方对容器化部署的支持立场需要如实转述：CryptPad 官方文档与配置文件免责声明明确「官方仅正式推荐独立 Node.js 服务器与 NGINX 反代两种运行方式，不正式推荐/支持 Apache、Docker、Kubernetes、Traefik 等其他配置」；但官方仓库与 Docker Hub 组织又长期维护官方镜像与 docker-compose.yml。本文即按官方 Compose 方案实测，遇到的问题与解法全部沉淀在第四章与第十一章。

三、前置条件

  1. 一台 Ubuntu 22.04 服务器，已安装 Docker Engine 与 Compose 插件（docker --version、docker compose version 可执行）；
  2. 磁盘余量：基础部署 ≥ 3 GB；若启用 OnlyOffice 三件套（第十、章），镜像解包后再需约 900 MB 数据卷，建议预留 5 GB；
  3. 端口未被占用：ss -ltn 确认 8145、8147 空闲；
  4. （生产）两个不同源的域名与 TLS 证书，或先按本篇完成本机验证再迁域名；
  5. 官方最低硬件要求（来源：docs.cryptpad.org 管理员指南）：2 GB 内存、2 CPU、20 GB 存储。

四、部署步骤

4.1 创建部署目录

为 Compose 项目创建根目录，数据卷子目录随首启自动生成（也可预建）：

mkdir -p /opt/cryptpad && cd /opt/cryptpad

实测回显（创建后目录列表）：

ls -la /opt/cryptpad/

total 28
drwxr-xr-x 5 root root 4096 Oct 22 05:01 .
drwxr-xr-x 9 root root 4096 Oct 22 05:01 ..
-rw-r--r-- 1 root root 1160 Oct 22 05:01 docker-compose.yml
drwxr-xr-x 5 4001 4001 4096 Oct 22 05:01 data
drwxr-xr-x 2 root root 4096 Oct 22 05:01 config
drwxr-xr-x 2 4001 4001 4096 Oct 22 05:01 customize
drwxr-xr-x 4 4001 4001 4096 Oct 22 05:01 onlyoffice-conf
drwxr-xr-x 4 4001 4001 4096 Oct 22 05:01 onlyoffice-dist

4.2 编写 docker-compose.yml

以官方仓库 2026.5.1 版 docker-compose.yml 为基础（来源：github.com/cryptpad/cryptpad，tag 2026.5.1），固定版本标签、补充显式项目名与容器名，写入 /opt/cryptpad/docker-compose.yml：

name: cryptpad-2026.5.1-stack

services:
  cryptpad:
    image: cryptpad/cryptpad:version-2026.5.1
    container_name: cryptpad-2026.5.1-web
    hostname: cryptpad
    environment:
      - CPAD_MAIN_DOMAIN=http://localhost:8145
      - CPAD_SANDBOX_DOMAIN=http://127.0.0.1:8145
      - CPAD_CONF=/cryptpad/config/config.js
      # 启用 OnlyOffice 三件套（表格/文档/演示），需先接受其许可，见第十、章
      - CPAD_INSTALL_ONLYOFFICE=yes
    volumes:
      - ./data/blob:/cryptpad/blob
      - ./data/block:/cryptpad/block
      - ./customize:/cryptpad/customize
      - ./data/data:/cryptpad/data
      - ./data/files:/cryptpad/datastore
      - ./onlyoffice-dist:/cryptpad/www/common/onlyoffice/dist
      - ./onlyoffice-conf:/cryptpad/onlyoffice-conf
    ports:
      - "8145:3000"
      - "8147:3003"
    ulimits:
      nofile:
        soft: 1000000
        hard: 1000000

⚠️ 注意：与官方 2026.5.1 compose 相比，本文固定了 version-2026.5.1 标签并显式声明 name（Compose 项目名）。多套 Compose 栈共存于同一台服务器时，显式项目名可避免 docker compose down 误伤其他同名项目。

ulimits.nofile（1000000）来自官方原配置：CryptPad 每个 WebSocket 连接占用一个文件描述符，官方把上限提到一百万以支撑并发。

4.3 首次启动与排障实录（数据目录属主）

先注释掉 CPAD_INSTALL_ONLYOFFICE 行（首启先跑通主服务，OnlyOffice 见第十、章），然后启动：

cd /opt/cryptpad && docker compose up -d

 Container cryptpad-2026.5.1-web Creating
 Container cryptpad-2026.5.1-web Created
 Container cryptpad-2026.5.1-web Starting
 Container cryptpad-2026.5.1-web Started

首次启动实测失败，日志（docker logs cryptpad-2026.5.1-web）如下：

> cryptpad@2026.5.1 start
> node server.js

/cryptpad/lib/log.js:99
            throw err;
            ^

[Error: EACCES: permission denied, mkdir '/cryptpad/data/logs'] {
  errno: -13,
  code: 'EACCES',
  syscall: 'mkdir',
  path: '/cryptpad/data/logs'
}

Node.js v24.16.0

原因定位：镜像内进程以非 root 用户 cryptpad（UID/GID 均为 4001，可用 docker run --rm --entrypoint id cryptpad/cryptpad:version-2026.5.1 实测确认）运行，而 Compose 首次启动时自动创建的宿主机 bind mount 目录属主是 root:root（755），服务进程无权写入 /cryptpad/data（对应宿主 ./data/data）等数据卷。

解决方案：把全部数据卷目录属主改为 4001:4001 后重建：

cd /opt/cryptpad
chown -R 4001:4001 data customize onlyoffice-conf onlyoffice-dist
docker compose up -d --force-recreate

 Container cryptpad-2026.5.1-web Starting
 Container cryptpad-2026.5.1-web Started

⚠️ 注意：onlyoffice-conf、onlyoffice-dist 两个目录即使首启不装 OnlyOffice 也一并改属主——第十、章实测它们同样会被 4001 进程写入，属主不改会在启用 OnlyOffice 时复发同类错误。

4.4 首启成功日志解读

属主修复后启动，日志依次输出三段关键信息（docker logs 实测节选）：

第一段，配置文件自动生成提示（容器内 /cryptpad/config/config.js 不存在时，入口脚本复制 config.example.js 并注入 CPAD_MAIN_DOMAIN/CPAD_SANDBOX_DOMAIN）：

         ####################################################################
         Warning: No config file provided for cryptpad
         We will create a basic one for now but you should rerun this service
         by providing a file with your settings
         eg: docker run -v /path/to/config.js:/cryptpad/config/config.js
         ####################################################################

第二段，前端构建（每次启动都会执行 npm run build，为各应用生成入口 HTML，耗时约 1 分钟，正常现象）：

> cryptpad@2026.5.1 build
> node scripts/build.js

Creating target directories
Parsing /cryptpad/www/sheet/index.html
Creating ./www/sheet/index.html
Parsing /cryptpad/www/pad/index.html
Creating ./www/pad/index.html
Parsing /cryptpad/www/kanban/index.html
Creating ./www/kanban/index.html
...
Copying built files to target directory (/cryptpad/customize)
Removing temporary build directory (/tmp/CRYPTPAD_TEMP_BUILD/)
Successfully removed /tmp/CRYPTPAD_TEMP_BUILD/

第三段，服务就绪并打印首次管理员引导链接（内含一次性安装令牌）：

> cryptpad@2026.5.1 start
> node server.js

=============================
Create your first admin account and customize your instance by visiting
http://localhost:8145/install/#669ba14a5387634fd1086d5689c9dfa24b64006e283fbb1eab4fc1d3590fa986
=============================

💡 说明：/install/#<令牌> 是创建第一个管理员账户的专用入口，令牌每次初始化随机生成、从服务日志获取；注册完管理员后该链接即失效。本文令牌来自一次性验证环境，读者应以自己实例日志中的为准。

4.5 健康验证

镜像自带健康检查（curl -f http://localhost:3000/，每 60 秒一次），先看状态：

docker compose ps --format '{{.Name}}: {{.Status}}'

cryptpad-2026.5.1-web: Up 2 minutes (healthy)

主页与配置接口：

curl -s -o /dev/null -w 'GET / -> HTTP %{http_code} (%{size_download}B)\n' http://localhost:8145/
curl -s -o /dev/null -w 'GET /api/config -> HTTP %{http_code} (%{size_download}B)\n' http://localhost:8145/api/config

GET / -> HTTP 200 (4019B)
GET /api/config -> HTTP 200 (560B)

/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
};
});

关键字段核对：httpUnsafeOrigin/httpSafeOrigin 与 compose 环境变量一致；defaultStorageLimit 52428800 = 50 MB（免费用户默认配额）；maxUploadSize 20971520 = 20 MB；inactiveTime 90 天。参数含义详见 《CryptPad 2026.5.1 配置参数详解》。

WebSocket 通道验证（协作实时同步依赖 3003 端口的 /cryptpad_websocket 升级）：

curl -s -o /dev/null -w 'WS /cryptpad_websocket -> HTTP %{http_code}\n' --max-time 8 \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  http://localhost:8147/cryptpad_websocket

WS /cryptpad_websocket -> HTTP 101

HTTP 101（Switching Protocols）即 WebSocket 握手成功。最后批量核对核心页面：

for p in /login/ /register/ /drive/ /checkup/ /install/; do printf '%-12s -> ' "$p"; \
  curl -s -o /dev/null -w 'HTTP %{http_code}\n' "http://localhost:8145$p"; done

/login/       -> HTTP 200
/register/    -> HTTP 200
/drive/       -> HTTP 200
/checkup/     -> HTTP 200
/install/     -> HTTP 200

💡 说明：/checkup/ 是实例内置自检页，浏览器打开后可逐项检查域名/沙箱/Service Worker 等客户端侧配置，是双域配置排障的第一入口。

4.6 排障实录（沙箱源与 3001 端口）

本篇初版实验曾把沙箱域配置到独立端口（CPAD_SANDBOX_DOMAIN=http://127.0.0.1:8146 并映射 8146:3001），实测沙箱源始终连不通：

=== sandbox 源 8146 ===
HTTP 000

原因定位：镜像内 lib/env.js 的逻辑是——只有当 httpSafeOrigin 未显式配置（非字符串，开发模式）时，服务才会派生并在 httpSafePort（默认 httpPort + 1，即 3001）上额外启动一个监听；一旦显式设置了 httpSafeOrigin（生产模式），httpSafePort 保持未定义、3001 不再监听，沙箱内容由反向代理把沙箱域名转发到主服务端口来实现。官方 docs/example.nginx.conf 亦印证：your-main-domain.com 与 your-sandbox-domain.com 两个 server 块最终都 proxy_pass http://localhost:3000（WebSocket 路径 /cryptpad_websocket 单独转发到 3003）。

解决方案：沙箱域与主域指向同一服务端口、仅主机名不同——CPAD_MAIN_DOMAIN=http://localhost:8145 + CPAD_SANDBOX_DOMAIN=http://127.0.0.1:8145，去掉 8146 映射。修复后两个源均返回 HTTP 200（见 4.5）。

五、数据持久化说明

5.1 数据卷对照表

宿主目录（/opt/cryptpad/）容器内路径存储内容（官方 config 注释归纳）
data/files/cryptpad/datastore协作文档（pad）主存储，每文档一个文件
data/blob/cryptpad/blob用户上传的加密文件块
data/block/cryptpad/block用户认证块（登录凭据派生）
data/data/cryptpad/data综合：pins/（钉住记录）、archive/（删除归档）、tasks/（定时任务）、logs/（NDJSON 日志）、blobstage/（上传暂存）、decrees/（操作日志）
customize/cryptpad/customize构建产物与自定义覆盖（每次启动 npm run build 写入）
onlyoffice-conf/cryptpad/onlyoffice-confOnlyOffice 版本属性（onlyoffice.properties）
onlyoffice-dist/cryptpad/www/common/onlyoffice/distOnlyOffice 静态资源（启用后约 886 MB）

首启后实测落盘情况：

ls /opt/cryptpad/data/data/

archive  blobstage  decrees  logs  pins  tasks

5.2 重启持久化实测

cd /opt/cryptpad && docker compose restart

 Container cryptpad-2026.5.1-web Started

sleep 25 && docker compose ps --format '{{.Name}}: {{.Status}}' && \
  curl -s -o /dev/null -w '重启后 GET / -> HTTP %{http_code}\n' http://localhost:8145/ && \
  ls data/data/ | tr '\n' ' '; echo

cryptpad-2026.5.1-web: Up 25 seconds (health: starting)
重启后 GET / -> HTTP 200
archive blobstage decrees logs pins tasks

数据目录原样保留、服务自动恢复。备份策略：停写窗口内对 /opt/cryptpad/data、/opt/cryptpad/data/files、/opt/cryptpad/data/blob、/opt/cryptpad/data/block 做快照即可完整保住全部用户数据。

六、环境变量表

以下变量由镜像入口脚本 docker-entrypoint.sh 消费（2026.5.1 版源码逐条核对）：

变量作用实测行为
CPAD_MAIN_DOMAIN主域 URL，注入 config.js 的 httpUnsafeOrigin必填；http://localhost:8145 实测注入成功
CPAD_SANDBOX_DOMAIN沙箱域 URL，注入 httpSafeOrigin，必须与主域不同源必填；http://127.0.0.1:8145 实测注入成功
CPAD_CONF配置文件路径设为 /cryptpad/config/config.js；文件不存在时入口脚本从 config.example.js 复制并注入上面两个域名
CPAD_INSTALL_ONLYOFFICE等于 yes 时启动前执行 ./install-onlyoffice.sh --accept-license --trust-repository实测下载 556.5 MB 的 onlyoffice-editor.zip 并解包（见第十、章）

⚠️ 注意：仅当 CPAD_CONF 指向的文件不存在时入口脚本才自动生成配置；一旦文件已存在（例如挂载了宿主配置），环境变量域名注入不再生效，改域名必须直接改 config.js（见第八、章）。

七、生产域名配置说明

本篇主线用 localhost/127.0.0.1 双源完成本机验证；生产部署替换规则如下：

  1. CPAD_MAIN_DOMAIN=https://pad.example.com（主域），CPAD_SANDBOX_DOMAIN=https://pad-sandbox.example.com（沙箱域）——两者必须不同源，官方推荐用子域名区分；
  2. 域名替换后需要删除旧配置再重建：容器内生成的 config.js 已固化旧域名，若采用第八、章的挂载方案则直接改宿主 config/config.js；
  3. 前置反向代理（NGINX）按官方 docs/example.nginx.conf 配置：主域与沙箱域两个 HTTPS server 块都反代到容器内 3000 端口，/cryptpad_websocket 路径反代到 3003，且需生成一张覆盖两个域名的证书（官方注释原文：两个域名共用一张证书）；
  4. 强烈建议 HTTPS：CryptPad 的 Service Worker 与部分加密 API 依赖安全上下文，官方注释明确「生产实例只应通过 HTTPS 提供」。

八、配置文件挂载

首启自动生成的配置落在容器可写层（/cryptpad/config/config.js），重建容器即丢。生产做法是把配置目录挂到宿主并预置配置：

cd /opt/cryptpad
# 首启后先把容器内生成的 config.js 取出作为底稿
docker cp cryptpad-2026.5.1-web:/cryptpad/config/config.js ./config/config.js

在 compose 的 volumes: 段补一行挂载后 up -d 重建：

    volumes:
      - ./config:/cryptpad/config

之后所有配置变更直接改宿主 /opt/cryptpad/config/config.js，docker compose restart 生效。实测生成的配置中双域已被正确替换（宿主取出文件实测节选）：

51:    httpUnsafeOrigin: 'http://localhost:8145',
72:    httpSafeOrigin: 'http://127.0.0.1:8145',
80:    httpAddress: '0.0.0.0',

全部参数逐项解读见 《CryptPad 2026.5.1 配置参数详解》。

九、等价 docker run 参考

与上述 compose 等价的最小 docker run 命令（便于理解 compose 各字段；生产仍建议用 compose 管理）：

docker run -d \
  --name cryptpad-2026.5.1-web \
  -p 8145:3000 -p 8147:3003 \
  -e CPAD_MAIN_DOMAIN=http://localhost:8145 \
  -e CPAD_SANDBOX_DOMAIN=http://127.0.0.1:8145 \
  -e CPAD_CONF=/cryptpad/config/config.js \
  --ulimit nofile=1000000:1000000 \
  -v /opt/cryptpad/data/blob:/cryptpad/blob \
  -v /opt/cryptpad/data/block:/cryptpad/block \
  -v /opt/cryptpad/customize:/cryptpad/customize \
  -v /opt/cryptpad/data/data:/cryptpad/data \
  -v /opt/cryptpad/data/files:/cryptpad/datastore \
  -v /opt/cryptpad/onlyoffice-dist:/cryptpad/www/common/onlyoffice/dist \
  -v /opt/cryptpad/onlyoffice-conf:/cryptpad/onlyoffice-conf \
  cryptpad/cryptpad:version-2026.5.1

十、OnlyOffice 三件套安装

CryptPad 自 2024 年起不再捆绑 OnlyOffice，表格/文档/演示三件套需要单独安装。容器化路径下由环境变量 CPAD_INSTALL_ONLYOFFICE=yes 触发，入口脚本在服务启动前执行：

./install-onlyoffice.sh --accept-license --trust-repository

安装脚本会先在 onlyoffice-conf/onlyoffice.properties 里记录版本水位（首装输出实测）：

'oldest_needed_version' is not set. Setting it to v9.

随后下载并校验 OnlyOffice 编辑器包（实测 56 秒下载完成，网速约 10 MB/s）：

  % Total    % Received % Xferd  Average Speed  Time    Time    Time   Current
                                 Dload  Upload  Total   Spent   Left   Speed
100 556.5M  100 556.5M    0     0  9.86M      0  00:56  00:56         8.78M
onlyoffice-editor.zip: OK
Archive:  onlyoffice-editor.zip

启动后核对产物与功能页：

du -sh /opt/cryptpad/onlyoffice-dist && ls /opt/cryptpad/onlyoffice-dist/ && cat /opt/cryptpad/onlyoffice-conf/onlyoffice.properties

886M    /opt/cryptpad/onlyoffice-dist
v9  x2t
oldest_needed_version=v9

for p in /sheet/ \
  /common/onlyoffice/dist/v9/web-apps/apps/spreadsheeteditor/main/index.html \
  /common/onlyoffice/dist/v9/web-apps/apps/documenteditor/main/index.html; do \
  printf '%-88s -> ' "$p"; curl -s -o /dev/null -w 'HTTP %{http_code} (%{size_download}B)\n' "http://localhost:8145$p"; done

/sheet/                                                                                    -> HTTP 200 (4357B)
/common/onlyoffice/dist/v9/web-apps/apps/spreadsheeteditor/main/index.html                 -> HTTP 200 (145575B)
/common/onlyoffice/dist/v9/web-apps/apps/documenteditor/main/index.html                    -> HTTP 200 (123452B)

v9 为主版本目录、x2t 为格式转换引擎，/sheet/ 页面与 OnlyOffice 静态资源均返回 200，即三件套安装成功。排障实录：本次实测首次启用时报 ./install-onlyoffice.sh: line 134: /cryptpad/onlyoffice-conf/onlyoffice.properties: Permission denied，原因即 4.3 所述——onlyoffice-conf 卷由 Compose 自动创建为 root:root，安装脚本以 4001 用户无法写入；执行 chown -R 4001:4001 onlyoffice-conf onlyoffice-dist 后重建即恢复。

⚠️ 注意：OnlyOffice 编辑器自带许可条款（AGPL 及第三方组件许可），官方要求启用前阅读并接受；升级 CryptPad 版本后需随新镜像重跑安装以匹配 oldest_needed_version 水位。

十一、常用运维命令

cd /opt/cryptpad

docker compose ps                      # 栈状态与健康检查（healthy / health: starting）
docker compose logs -f --tail=100      # 跟踪服务日志（构建/启动/运行日志都在这里）
docker compose restart                 # 重启（数据卷持久化，实测见 5.2）
docker compose stop                    # 停止
docker compose up -d                   # 启动/应用配置变更
docker compose pull                    # 拉取镜像更新
docker compose down                    # 停止并删除（数据卷在宿主目录，不受影响）

docker compose pull 实测回显（当前已是最新标签）：

 Image cryptpad/cryptpad:version-2026.5.1 Pulling
 Image cryptpad/cryptpad:version-2026.5.1 Pulled

升级流程：把 compose 中 image: 的标签换成新版本号（如未来发布 version-2026.10.0 后）→ docker compose pull → docker compose up -d；数据卷原样复用，入口脚本会自动重跑构建与必要的初始化。回滚＝把标签改回旧版本号执行同样两步。

日常巡检：docker compose ps 看 healthy；curl -s http://localhost:8145/api/config | grep -E 'httpUnsafeOrigin|httpSafeOrigin' 核对双域下发；磁盘重点盯 data/blob（文件上传）与 onlyoffice-dist（886 MB 固定占用）。服务端 NDJSON 运行日志在 data/data/logs/<UTC日期>/ 下，按天分目录。服务端管理脚本（清理过期数据、统计、管理员密钥生成等）见 《CryptPad 2026.5.1 常用 CLI 命令与工具详解》。

十二、常见问题

Q1：启动即报 EACCES: permission denied, mkdir '/cryptpad/data/logs'？ 数据卷属主问题：容器进程 UID 为 4001，Compose 自动创建的宿主目录属主是 root。执行 chown -R 4001:4001 data customize onlyoffice-conf onlyoffice-dist 后 docker compose up -d --force-recreate（实测见 4.3）。

Q2：页面白屏或应用打不开？ 九成是沙箱域配置错误（官方 config 注释原话：新实例的大多数问题源于此）。先用 /checkup/ 自检页定位，再核对 CPAD_SANDBOX_DOMAIN 与主域是否不同源、反代是否把沙箱域转发到了主服务端口（见 4.6）。

Q3：为什么 3001 端口没有监听？ 显式设置 httpSafeOrigin（生产模式）时服务不在 httpSafePort 上起监听，沙箱内容由反向代理转发主服务端口实现；只有完全不配置 httpSafeOrigin 的本机开发模式才会在 3001 起监听（源码 lib/env.js 逻辑，实测见 4.6）。

Q4：启用 OnlyOffice 报 onlyoffice.properties: Permission denied？ onlyoffice-conf、onlyoffice-dist 卷属主问题，chown -R 4001:4001 后重建（实测见第十、章）。

Q5：改了环境变量里的域名但不生效？ CPAD_CONF 指向的 config.js 已存在时入口脚本跳过生成，环境变量不再注入。删除容器内旧配置重建，或改用第八、章的宿主挂载方式直接维护 config.js。

Q6：忘记第一时间注册管理员怎么办？ 首启日志里的 /install/#<令牌> 链接即管理员注册入口，可用 docker compose logs | grep -A1 'Create your first admin' 重新找回；若令牌已失效，服务端可用 node scripts/install.js 重新生成安装令牌（脚本用法与已知问题见命令篇）。

Q7：卸载如何清理干净？ docker compose down 后删除 /opt/cryptpad 目录即可（全部持久化数据都在该目录内）；镜像按需 docker rmi cryptpad/cryptpad:version-2026.5.1。

十三、参考链接

资料链接
官方仓库（compose/nginx 样例）https://github.com/cryptpad/cryptpad
官方镜像https://hub.docker.com/r/cryptpad/cryptpad
官方安装文档https://docs.cryptpad.org/en/admin_guide/installation.html
官方 NGINX 反代样例https://github.com/cryptpad/cryptpad/blob/2026.5.1/docs/example.nginx.conf
本系列认知篇《CryptPad 介绍与选型指南》
本系列配置篇《CryptPad 2026.5.1 配置参数详解》
本系列命令篇《CryptPad 2026.5.1 常用 CLI 命令与工具详解》