SeaDoc 是 Seafile 的在线协作文档编辑扩展，可用于编写和维护产品文档、技术文档、知识库、在线手册和内部 Wiki。
SeaDoc 提供直观的文档编辑体验，并支持以下功能：
-
审阅与批准工作流程，便于管理文档修改；
-
文档间链接，方便组织和关联内容；
-
AI 集成，辅助内容生成、摘要和管理；
-
API 接口，用于自动化文档生成和处理。
本文适用于 Seafile 14.0 和 13.0。单节点 Docker 部署通常已集成 SeaDoc；集群部署或 Seafile 二进制部署可采用独立部署方式。
SeaDoc 架构
用户在浏览器中打开
.sdoc
文档时，内容加载流程如下：
-
浏览器通过对外访问地址向 SeaDoc 服务（ sdoc-server ）发送文档加载请求。
-
SeaDoc 向 Seafile 服务器请求文档内容。
-
SeaDoc 将文档内容返回浏览器。
使用 Caddy、Nginx 或 Apache 等反向代理时，浏览器请求需要正确转发至 SeaDoc，WebSocket 请求也必须正常代理。
在单节点 Docker 部署中使用 SeaDoc
使用官方 Docker Compose 部署 Seafile 单节点服务时，SeaDoc 默认作为扩展集成，无需额外单独部署。如果原部署未启用 SeaDoc，可按以下步骤配置。
1. 下载
seadoc.yml
进入 Seafile 的 Docker Compose 配置目录：
cd /opt/seafile
Seafile 14.0：
wget https://manual.seafile.com/14.0/repo/docker/seadoc.yml
Seafile 13.0：
wget https://manual.seafile.com/13.0/repo/docker/seadoc.yml
如果目录中已有
seadoc.yml
，无需重复下载；更新文件前应先备份现有配置。
2. 启用 SeaDoc
编辑
/opt/seafile/.env
，确保
COMPOSE_FILE
包含
seadoc.yml
，并设置：
ENABLE_SEADOC=true
例如，Seafile 使用 Caddy 反向代理、且只启用了 Seafile 和 SeaDoc 时：
COMPOSE_FILE='seafile-server.yml,caddy.yml,seadoc.yml'
ENABLE_SEADOC=true
COMPOSE_FILE
的内容应与实际部署的服务一致。如果已经配置了搜索引擎、通知服务器等其他服务，
必须保留这些组件对应的 YAML 文件
，不要直接用示例覆盖整个变量。使用其他反向代理时，也不应重新加入已停用的
caddy.yml
。
3. 启动并检查服务
docker compose up -d
docker compose ps
docker compose logs -f seadoc
确认 SeaDoc 容器正常运行后，可在 Seafile 网页端创建或打开
.sdoc
文档进行验证。
如果不再使用 SeaDoc，可以将
seadoc.yml
从
COMPOSE_FILE
中移除，并设置：
ENABLE_SEADOC=false
随后根据实际部署情况停止不再需要的 SeaDoc 容器并应用 Docker Compose 配置。
独立部署 SeaDoc
如果 Seafile 采用集群部署，或者通过二进制安装包部署，可将 SeaDoc 作为独立 Docker 服务部署。独立部署的 SeaDoc 需要连接 Seafile 使用的数据库，并通过反向代理提供访问入口。
以下示例将 SeaDoc 的 Docker Compose 配置放在
/opt/seadoc
，数据保存到
/opt/seadoc-data
。
1. 下载配置文件
mkdir -p /opt/seadoc
cd /opt/seadoc
Seafile 14.0：
wget https://manual.seafile.com/14.0/repo/docker/seadoc/seadoc.yml
wget -O .env https://manual.seafile.com/14.0/repo/docker/seadoc/env
Seafile 13.0：
wget https://manual.seafile.com/13.0/repo/docker/seadoc/seadoc.yml
wget -O .env https://manual.seafile.com/13.0/repo/docker/seadoc/env
2. 配置环境变量
编辑
/opt/seadoc/.env
，按实际环境填写以下变量：
变量名
说明
SEADOC_VOLUME
SeaDoc 数据持久化目录，默认可使用
/opt/seadoc-data
SEAFILE_MYSQL_DB_HOST
Seafile 数据库的地址，必须从 SeaDoc 容器内可访问
SEAFILE_MYSQL_DB_USER
数据库用户名，通常为
seafile
SEAFILE_MYSQL_DB_PASSWORD
数据库用户密码
TIME_ZONE
时区，例如
Asia/Shanghai
JWT_PRIVATE_KEY
JWT 密钥，
必须与 Seafile 的配置相同
SEAFILE_SERVER_HOSTNAME
Seafile 对外访问的域名或主机名
SEAFILE_SERVER_PROTOCOL
Seafile 对外访问协议，
http
或
https
独立部署模板还支持按需设置
SEAFILE_MYSQL_DB_PORT
（默认
3306
）和
SEADOC_MYSQL_DB_NAME
（默认
seahub_db
）。如果使用非默认数据库端口或数据库名，请确保相应变量与实际部署一致。
示例（请将地址和密码改为实际值）：
COMPOSE_FILE='seadoc.yml'
SEADOC_VOLUME=/opt/seadoc-data
SEAFILE_MYSQL_DB_HOST=192.168.0.2
SEAFILE_MYSQL_DB_USER=seafile
SEAFILE_MYSQL_DB_PASSWORD=your-database-password
TIME_ZONE=Asia/Shanghai
JWT_PRIVATE_KEY=your-existing-seafile-jwt-private-key
SEAFILE_SERVER_HOSTNAME=seafile.example.com
SEAFILE_SERVER_PROTOCOL=https
注意：
不要为 SeaDoc 生成与 Seafile 不同的
JWT_PRIVATE_KEY
。独立部署机器还需要能够访问 Seafile 服务和对应的 MySQL/MariaDB 数据库。
3. 配置 SeaDoc 监听端口
独立部署模板默认将 SeaDoc 容器的
80
端口映射到宿主机
80
端口。如果该端口已被其他服务占用，可编辑
/opt/seadoc/seadoc.yml
中的
seadoc
服务，调整已有的
ports
：
services:
seadoc:
ports:
- "127.0.0.1:8888:80"
以上只展示需要修改的字段，
不要用该片段替换整个
seadoc.yml
。该示例适用于 Nginx 与 SeaDoc 位于同一台机器的场景，SeaDoc 仅监听本机
8888
端口。
如果反向代理运行在另一台机器，请根据网络环境使用可被代理服务器访问的宿主机地址和端口，并限制防火墙访问范围。后续 Nginx 示例中的
127.0.0.1:8888
也应相应替换。
4. 配置反向代理
需要将
/sdoc-server/
和 WebSocket 使用的
/socket.io
路径代理到 SeaDoc 服务。下列 Nginx 和 Apache 示例二选一即可。
使用 Nginx
在对外提供 Seafile 服务的 Nginx
server { ... }
块中添加：
location /sdoc-server/ {
proxy_pass http://127.0.0.1:8888/;
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $server_name;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 100m;
}
location /socket.io {
proxy_pass http://127.0.0.1:8888;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_redirect off;
proxy_buffers 8 32k;
proxy_buffer_size 64k;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_set_header X-NginX-Proxy true;
}
以上示例对应本机的
8888
端口；如果使用其他端口或独立代理服务器，请同步修改
proxy_pass
。
完成配置后检查并重新加载 Nginx：
sudo nginx -t
sudo systemctl reload nginx
使用 Apache
如果使用 Apache HTTP Server，可在相应的虚拟主机配置中添加：
<Location /sdoc-server/>
ProxyPass "http://127.0.0.1:8888/"
ProxyPassReverse "http://127.0.0.1:8888/"
</Location>
<Location /socket.io/>
# Apache HTTP Server 2.4.47 及以上版本
ProxyPass "http://127.0.0.1:8888/socket.io/" upgrade=websocket
</Location>
请确保已启用所需的代理模块，且 Apache 版本支持对应的 WebSocket 代理配置。代理地址应与 SeaDoc 的实际监听地址一致。
5. 启动 SeaDoc
在 SeaDoc 的配置目录执行：
cd /opt/seadoc
docker compose config --quiet
docker compose up -d
docker compose logs -f seadoc
6. 在 Seafile 中启用独立的 SeaDoc
SeaDoc 对外通过反向代理的
/sdoc-server
路径提供服务。需要在
Seafile 服务器
的
.env
中设置其对外访问地址，而不是填写 SeaDoc 容器的内部 IP 和端口。
例如，Seafile 通过
https://seafile.example.com
提供访问：
ENABLE_SEADOC=true
SEADOC_SERVER_URL=https://seafile.example.com/sdoc-server
确保
SEADOC_SERVER_URL
使用用户实际访问的域名和协议。
修改后重启 Seafile：
Docker 部署（包括 Docker 集群中的相关节点）：
cd /opt/seafile
docker compose down
docker compose up -d
二进制部署：
cd /opt/seafile/seafile-server-latest
./seahub.sh restart
如使用集群或负载均衡器，还需要保证各节点的 SeaDoc 相关配置一致，并正确转发外部请求。
SeaDoc 目录结构
独立部署时，SeaDoc 默认使用以下持久化目录：
-
/opt/seadoc-data ：SeaDoc 数据及运行时持久化文件目录。
-
/opt/seadoc-data/logs ：SeaDoc 日志文件目录。
如果通过
SEADOC_VOLUME
修改了持久化路径，上述路径也应按实际配置调整。单节点集成部署的 SeaDoc 数据路径由 Seafile 使用的
.env
中的
SEADOC_VOLUME
决定。
SeaDoc 使用的数据库
SeaDoc 使用 Seafile 的
seahub_db
数据库中的
sdoc_operation_log
表保存操作日志，该表会自动清理。
使用独立部署时，应确保 SeaDoc 配置的数据库与 Seafile 实际使用的数据库一致。默认数据库名不是
seahub_db
时，需要同步修改相应的环境变量。
SeaDoc 故障排查
打开
.sdoc
文件时，浏览器首先连接 SeaDoc，随后由 SeaDoc 获取 Seafile 中的文档内容。可按以下顺序排查。
浏览器无法连接 SeaDoc
例如，页面出现
Server is disconnected. Reconnecting…
。
-
检查 ENABLE_SEADOC=true ，并确认 SEADOC_SERVER_URL 使用正确的对外域名及协议。
-
在浏览器打开 https://你的域名/sdoc-server/ ；若返回 Welcome to sdoc-server ，说明该入口可正常访问。
-
使用 Nginx 或 Apache 时，检查 /sdoc-server/ 和 /socket.io 的转发规则，尤其是 WebSocket 的 Upgrade 、 Connection 头。
-
检查 SeaDoc 容器运行状态和日志：
docker compose ps
docker compose logs -f seadoc
如果仍然无法连接，可使用浏览器开发者工具查看 Network 和 WebSocket 请求的状态。
SeaDoc 无法从 Seafile 加载文档
例如，页面出现
Load doc content error
。
-
单节点集成部署： SeaDoc 默认通过 Docker 服务名 http://seafile 访问 Seafile。确认相关容器位于可通信的 Docker 网络中。
-
独立部署： 检查 SeaDoc 的 .env 中 SEAFILE_SERVER_HOSTNAME 和 SEAFILE_SERVER_PROTOCOL 是否正确，并确认 SeaDoc 容器能访问对应地址。
-
检查 SeaDoc 的 JWT_PRIVATE_KEY 是否与 Seafile 一致，以及数据库连接是否正常。
-
查看 SeaDoc 日志中是否存在连接、认证或数据加载错误。
