Seafile 12.0.14 配置参数详解

目标：把 Seafile CE 12.0.14 服务端的全部配置文件逐文件、逐参数讲清——每个参数的实测默认值/实测取值、作用与改动影响，给出修改生效方式与一份小团队生产配置模板。全部参数取自 Ubuntu 22.04.5 实测环境的真实配置文件（2026-10-22 实录），逐块附原文与解读。安装过程见 《Ubuntu 22.04 安装 Seafile 指南》。

一、环境信息

本章列出本篇参数实测环境的基线（与安装篇同一环境）：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Seafile：社区版（CE）12.0.14（seafile-server_12.0.14_x86-64.tar.gz）
• 数据库：MariaDB 10.6.23；运行时：Python 3.11（3.11.0rc1）
• 演示服务器地址：http://10.89.59.2；Seahub 端口 8130、FileServer 端口 8131（默认 8000/8082，实测因端口冲突改绑）
• 安装根目录：/opt/seafile；配置目录：/opt/seafile/conf/
• 账号：MariaDB root/q1w2e3r4；数据库用户 seafile/q1w2e3r4（host 127.0.0.1）

二、前置条件

本章说明阅读与操作本篇的前提：

• 已按 《Ubuntu 22.04 安装 Seafile 指南》 完成 12.0.14 安装并能登录 Web；
• 具备 root/sudo 权限，能编辑 /opt/seafile/conf/ 下的文件并重启服务；
• 注意 12.0 结构变化：独立 ccnet-server 已移除，配置目录下没有 ccnet.conf（实测 conf/ 清单见 3.1），旧版教程里的 ccnet 相关参数不再适用。

三、参数查看与修改方式

3.1 配置文件位置与清单

12.0 的全部服务端配置集中在 /opt/seafile/conf/（实测清单）：

ls -la /opt/seafile/conf/

total 36
drwxr-xr-x  3 root root 4096 Oct 22 02:21 .
drwxr-xr-x 10 root root 4096 Oct 22 02:12 ..
-rw-r--r--  1 root root   61 Oct 22 02:12 .env
drwxr-xr-x  2 root root 4096 Oct 22 02:21 __pycache__
-rw-r--r--  1 root root  379 Oct 22 02:21 gunicorn.conf.py
-rw-r--r--  1 root root   53 Oct 22 02:12 seafdav.conf
-rw-r--r--  1 root root  392 Oct 22 02:12 seafevents.conf
-rw-r--r--  1 root root  207 Oct 22 02:22 seafile.conf
-rw-r--r--  1 root root  400 Oct 22 02:21 seahub_settings.py

3.2 修改与生效流程

统一流程（每步都验证）：编辑文件 → 重启对应单元 → 验证端口/行为。重启命令（每行一个单元）：

systemctl restart seafile.service

systemctl restart seahub.service

重启后用探针验证控制面（实测回显）：

curl -s http://127.0.0.1:8130/api2/ping/

"pong"

⚠️ 两条硬经验（实测踩坑）：① 改配置不重启不生效，Type=oneshot 的单元必须 systemctl restart；② 不要重跑安装脚本来"应用"配置——重复 setup 会覆盖 conf/ 下文件（实测 SECRET_KEY、SERVICE_URL、gunicorn bind 均被还原重新生成）。

四、参数总览

先给一张全局速查表（「默认值」列为安装脚本生成时的实测值，「实测值」列为本环境当前实测值）：

关键差异解读：真正需要动的高频参数集中在 5 个——[fileserver] port、bind、SERVICE_URL、tmp_file_dir、workers；其余多数保持默认即可。

五、核心参数分类详解

5.1 seafile.conf：存储引擎与数据库

实测文件原文：

[fileserver]
port = 8131
tmp_file_dir = /opt/seafile/seafile-data/tmp

[database]
type = mysql
host = 127.0.0.1
port = 3306
user = seafile
password = q1w2e3r4
db_name = seafile_db
connection_charset = utf8

逐项说明：

• [fileserver] port：数据面（文件上传/下载/同步块传输）端口，默认 8082；本环境因冲突改 8131。改动后需重启 seafile.service，且 Web 端分享外链里的文件地址会随 SERVICE_URL/FILE_SERVER_ROOT 语义联动，改端口后务必浏览器实测上传下载。
• [fileserver] tmp_file_dir：上传临时文件目录。实测安装脚本默认不生成该项也不创建目录，缺目录时上传报 500（Failed to open temp file），需手动 mkdir -p 并写入该项（本环境实测已补）。
• [database] 各项：存储引擎连接 seafile_db 的连接四件套（host/port/user/password）+ 库名与字符集。注意这里的 user 是安装脚本创建的专用用户，host 为 127.0.0.1；改密码需同步改 MariaDB 侧与本文件两处。

5.2 seahub_settings.py：Web 应用配置

实测文件原文：

# -*- coding: utf-8 -*-
SECRET_KEY = "wi=snjxgas@ek1w+3kw^pi0s$6=sdv)hc!z%=l78#j4$xhds#l"
SERVICE_URL = "http://10.89.59.2:8130"

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'seahub_db',
        'USER': 'seafile',
        'PASSWORD': 'q1w2e3r4',
        'HOST': '127.0.0.1',
        'PORT': '3306',
        'OPTIONS': {'charset': 'utf8mb4'},
    }
}

逐项说明：

• SECRET_KEY：Django 会话与令牌签名密钥，安装脚本自动随机生成，每台服务器不同（上面为演示环境实测值，生产严禁照抄）。⚠️ 丢失或更换会导致所有已有会话与分享链接签名失效；重跑 setup 会重新生成该值（实测踩坑）。
• SERVICE_URL：对外服务地址，浏览器访问与分享链接的基准。本环境实测为 http://10.89.59.2:8130（含端口）。改绑 seahub 端口后必须同步修改。
• DATABASES：seahub_db 的 Django 连接配置，字符集 utf8mb4（注意与 seafile.conf 的 utf8 不同，各自独立，保持脚本生成值即可）。

5.3 gunicorn.conf.py：进程与监听

实测文件原文：

import os

daemon = False
workers = 5

# default localhost:8000
bind = "0.0.0.0:8130"

# Pid
pids_dir = '/opt/seafile/pids'
pidfile = os.path.join(pids_dir, 'seahub.pid')

# for file upload, we need a longer timeout value (default is only 30s, too short)
timeout = 1200

limit_request_line = 8190

# for forwarder headers
forwarder_headers = 'SCRIPT_NAME,PATH_INFO,REMOTE_USER'

逐项说明：

• daemon：是否由 gunicorn 自行守护化。本环境实测为 False（前台运行，由 systemd 托管生命周期）；该值决定 seahub.sh start 是否阻塞，排障时改 False 可直接看前台日志。
• workers：worker 进程数，默认 5；实测 ss -tlnp 可见 5 个 python3.11 进程共用监听 fd。小内存机器可降到 2–3。
• bind：seahub 监听地址，默认 0.0.0.0:8000（脚本注释原文 default localhost:8000）；本环境改绑 0.0.0.0:8130。改这里 + SERVICE_URL 两处即可完成 seahub 端口改绑。
• pids_dir/pidfile：pid 文件目录与位置；重复启动报 Already running on PID ... 或 pid 文件残留时按此路径清理。
• timeout：请求超时 1200 秒（注释原文说明默认 30 秒对文件上传太短）；大文件上传场景不要调小。
• limit_request_line：请求行长度上限 8190；分享链接带长 token 时避免 414。
• forwarder_headers：置于反向代理后需要透传的头。

5.4 seafdav.conf：WebDAV

实测文件原文：

[WEBDAV]
enabled = false
port = 8080
share_name = /

逐项说明：enabled 默认关闭；启用后 WebDAV 服务监听 port（默认 8080，与其他服务改绑时注意错开），share_name 为客户端挂载路径名。启用流程：改 enabled = true → 重启服务 → 用 http://<服务器>:<port>/ 挂载验证。

5.5 seafevents.conf：扩展能力

实测文件原文：

[DATABASE]
type = mysql
host = 127.0.0.1
port = 3306
username = seafile
password = q1w2e3r4
name = seahub_db

[SEAHUB EMAIL]
enabled = true

## interval of sending Seahub email. Can be s(seconds), m(minutes), h(hours), d(days)
interval = 30m

# Enable statistics
[STATISTICS]
enabled=true

# Enable file history
[FILE HISTORY]
enabled = true
suffix = md,txt,doc,docx,xls,xlsx,ppt,pptx,sdoc

逐项说明：[DATABASE] 与 seahub 共库（seahub_db），凭据同 5.2；[SEAHUB EMAIL] 控制系统邮件发送，interval 支持 s/m/h/d 单位；[STATISTICS] 开关访问统计；[FILE HISTORY] 的 suffix 决定哪些后缀的文件记录历史版本。

5.6 .env：JWT 私钥

12.0 起必需。缺失时启动报错（实测回显）：

Cannot find JWT_PRIVATE_KEY value from environment, try to read .env file.

生成与查看（实测命令与回显）：

echo "JWT_PRIVATE_KEY=$(openssl rand -base64 32)" > /opt/seafile/conf/.env
cat /opt/seafile/conf/.env

JWT_PRIVATE_KEY=HNNLecIRG1AK4Xg8esHdgNA1kMvTBvDSJoHztX23TM0=

⚠️ 必须位于 /opt/seafile/conf/（12.0 集中配置目录），放在安装根目录实测无效；值必须每台服务器独立生成。

六、生产配置模板

适用场景：2 核 4GB 内存 / NVMe SSD / 50 人以内小团队的 Ubuntu 22.04 单机。整合高频改动项的模板（⚠️ SECRET_KEY 与 JWT_PRIVATE_KEY 必须用各自机器的实测生成值，禁止照抄演示值）：

# /opt/seafile/conf/seafile.conf
[fileserver]
port = 8131
tmp_file_dir = /opt/seafile/seafile-data/tmp

[database]
type = mysql
host = 127.0.0.1
port = 3306
user = seafile
password = q1w2e3r4
db_name = seafile_db
connection_charset = utf8

# /opt/seafile/conf/gunicorn.conf.py（节选，其余保持脚本生成值）
daemon = False
workers = 3          # 4GB 内存建议 3，8GB 可保持 5
bind = "0.0.0.0:8130"
timeout = 1200

# /opt/seafile/conf/seahub_settings.py（节选）
SERVICE_URL = "http://<你的服务器地址或域名>:8130"

模板要点：tmp_file_dir 必配且目录必须存在；workers 按内存分档；SERVICE_URL 与 bind 端口保持一致；改完逐一重启并按 3.2 验证。

七、常见问题（FAQ）

Q1：改了配置不生效 Type=oneshot 单元必须 systemctl restart seafile.service / systemctl restart seahub.service（对应关系见 3.1 表），并用 /api2/ping/ 验证控制面恢复。

Q2：上传报 500（Failed to open temp file） tmp_file_dir 指向的目录不存在（实测默认不创建）。mkdir -p /opt/seafile/seafile-data/tmp 后重启 seafile.service。

Q3：启动报 Cannot find JWT_PRIVATE_KEY value from environment, try to read .env file. .env 缺失或放错位置。必须在 /opt/seafile/conf/.env，按 5.6 重新生成。

Q4：重跑安装脚本后 SECRET_KEY/SERVICE_URL/bind 全变回默认 重复 setup 会覆盖 conf/ 文件（实测确认）。恢复定制项后重启；不要用重跑 setup 的方式改配置。

Q5：seahub 监听与 ss 看到的进程数对不上 workers = 5 时监听 fd 由多个 worker 共享（实测 ss 显示 5 个 python3.11 进程），属正常；判定存活的准据是端口 LISTEN 且探针返回 "pong"。

八、参考链接

• 官方手册（部署与配置文档）：https://manual.seafile.com/
• 官方下载页：https://www.seafile.com/download/
• GitHub 仓库：https://github.com/haiwen/seafile
• 站内延伸：《Seafile 介绍与选型指南》、《Ubuntu 22.04 安装 Seafile 指南》