Pydio Cells 配置参数详解

目标：把 Pydio Cells 5.1.0 的配置体系讲透——主配置文件 /var/cells/pydio.json 六大顶层段的每个核心参数（逐项实测取值）、cells admin config 命令行读写方式（实测闭环）、YAML 非交互安装的模型键，以及数据库连接 DSN 的逐参数解释。所有键名与取值均来自实机安装产物与实机命令回显（Ubuntu 22.04 + Cells Home Edition 5.1.0，实测日期 2026-10-22），安装过程见 《Ubuntu 22.04 安装 Pydio Cells 指南》。

一、环境信息

二、前置条件

• 已按 《Ubuntu 22.04 安装 Pydio Cells 指南》 完成安装，服务 systemctl is-active cells 为 active；
• 以 pydio 用户执行 cells admin config 系列命令（配置文件属主为 pydio）；
• 本文示例账号为 admin / q1w2e3r4；
• 理解 Cells 配置的双层结构：pydio.json 文件是配置的落盘形态，同时每项配置也会写入数据库（cells admin config set 的自述原文：「Store a configuration item in both the pydio.json file and in the database」）——因此改配置要么用命令行（双写、即时一致），要么改文件后重启服务让进程重新加载。

三、参数查看与修改方式

3.1 直接编辑 pydio.json

sudo vi /var/cells/pydio.json
sudo systemctl restart cells

改文件必须重启服务才生效。文件为标准 JSON，属主 pydio:pydio；手工编辑注意保留其中的模板变量（形如 {{.Meta.prefix}} 的 Go template 占位符，服务运行时动态求值）。

3.2 cells admin config 命令行

子命令清单（cells admin config --help 实测）：

查看全部配置（cells admin config list 实测，输出为 PATH/VALUE 两列表格，摘录关键行）：

| defaults/sites                                                               | [{"Binds":["0.0.0.0:8080"],"Routing":[{"Effect":1,"Matcher":"*"}],"TLSConfig":{"SelfSigned":{}}}]                    |
| frontend/secureCookies/SameSite                                              | Strict                                                                                                              |
| services/pydio.grpc.update/channel                                           | stable                                                                                                              |

有效性检查（实测输出）：

cells admin config check

Checking config at file:///var/cells/pydio.json?readOnly=true
✔ Default datasource set. A config process has already been performed.

写入配置项。语法为三个位置参数：服务名、参数名、JSON 编码的值（--help 实测示例：cells admin config set micro.web port 8083）。实测把更新通道改为大写再改回（回显逐字实录）：

cells admin config set pydio.grpc.update channel STABLE

✔ Config set
Delaying exit to make sure write operations are committed.

改后 cells admin config list 中该项即变为 STABLE（值原样存储，不做大小写归一），再执行 cells admin config set pydio.grpc.update channel stable 恢复。

⚠️ 实测说明（变更历史）：cells admin config history 在默认文件存储下返回 no revisions store found——file 配置存储不带修订记录库，配置变更历史需要其他存储后端（如 etcd）或事先有 revision store 才可用。排障时不要依赖 history 回溯文件存储的改动。

3.3 Web 管理设置界面

登录 Web 界面（https://<服务器IP>:8080，admin 账号）后，右上角进入管理设置区，可图形化管理的核心对象包括：用户与角色、工作区、数据源、访问策略（ACL）、分享链接策略、邮件通知模板、日志查看等（能力清单源自官方管理文档 docs.pydio.com Admin Guide，查询日期 2026-10-22）。这些图形化设置最终同样落到配置存储与数据库中；其中前端表现类参数在 pydio.json 有直接对应键，例如：

批量与无人值守场景建议用 3.1/3.2 的文件或命令行方式。

四、参数总览

pydio.json 共 6 个顶层段（实测结构）：

五、核心参数分类详解

5.1 数据库连接参数

主库定义在 databases 段（实测原文，DSN 中的 \u0026 是 JSON 对 & 的转义，实际值为 &）：

"databases": {
  "bf34088e3b2462b3fe25b9fc66da897ed4a70afc": {
    "driver": "sql",
    "dsn": "mysql://pydio:q1w2e3r4@tcp(localhost:3306)/cells?parseTime=true&prefix={{.Meta.prefix}}&policies={{.Meta.policies}}&singular={{.Meta.singular}}"
  }
},
"defaults": {
  "database": { "$ref": "#/databases/bf34088e3b2462b3fe25b9fc66da897ed4a70afc" }
}

DSN 逐参数解释（格式 mysql://用户:密码@tcp(主机:端口)/库名?参数串）：

defaults/database/$ref 用 JSON 引用把默认库指向上面这段定义。改数据库连接最稳妥的路径是重跑 cells configure，或用 cells admin config db 子命令（list 列出连接、set 为指定服务指派连接、move 在库之间迁移服务数据）。

5.2 站点与 TLS 参数

defaults/sites 数组定义内嵌网关的绑定与 TLS（实测原文）：

"sites": [
  {
    "Binds": ["0.0.0.0:8080"],
    "Routing": [{ "Effect": 1, "Matcher": "*" }],
    "TLSConfig": { "SelfSigned": {} }
  }
]

改站点参数的两个入口：cells configure sites 交互向导（安装指南 7.2 节），或 cells configure 的 --site_* 旗标族（实测 help 清单）：--site_bind（绑定地址）、--site_external（外部 URL）、--site_no_tls（纯 HTTP）、--site_tls_cert_file / --site_tls_key_file（自备证书）、--site_le_email / --site_le_agree / --site_le_staging（Let's Encrypt 三件套）。

5.3 默认数据源与存储参数

默认数据源（安装向导「Default storage location」选默认目录的产物）：

"defaults": { "datasource": "pydiods1" }

对象存储服务（文件实际落盘位置，实测原文节选）：

"pydio.grpc.data.objects.local1": {
  "Name": "local1",
  "RunningPort": 35873,
  "ApiKey": "LX9PiJQ9CsG71yj9",
  "ApiSecret": "38c4e545-31e3-47c1-8510-757c7ee13aee",
  "LocalFolder": "/var/cells/data"
}

各数据源同步服务以 pydio.grpc.data.sync.<名称> 定义，实测共性参数：

defaults/layout 定义两个默认工作区模板：Personal Files（slug personal-files，根为 my-files 模板，按用户名分流到 personal 数据源）与 Common Files（slug common-files，根为 DATASOURCE:pydiods1）——common-files 这个 slug 就是 WebDAV 路径 /dav/common-files/ 的来源（安装指南 4.7 节实测）。

5.4 前端与会话安全参数

实测 frontend 段原文（密钥类值已随安装随机生成，此处如实展示结构）：

"frontend": {
  "plugin": {
    "core.pydio": { "APPLICATION_TITLE": "Pydio Cells", "DEFAULT_LANGUAGE": "en-us" },
    "editor.libreoffice": { "LIBREOFFICE_HOST": "localhost", "LIBREOFFICE_PORT": "9980", "LIBREOFFICE_SSL": true }
  },
  "secureCookies": { "SameSite": "Strict" },
  "secureHeaders": { "X-XSS-Protection": "1; mode=block" },
  "session": { "secureKey": "<安装时随机生成的 64 字节 base64 密钥>" },
  "versionSeed": "dcb34de7-2b3e-4f10-bddd-006fbd7dbe4f"
}

• editor.libreoffice/*：LibreOffice 在线编辑集成参数（默认指向本机 9980，未部署该组件时不影响其他功能）；
• session/secureKey：会话签名密钥，丢失会导致全体会话失效，务必随 /var/cells 一起备份；
• defaults/personalTokens/secureKey：个人令牌（API/同步客户端授权）签名密钥，同样属备份清单；
• versionSeed：前端资源版本种子（缓存失效用，勿手改）。

5.5 更新与遥测参数

"defaults": {
  "update": {
    "updateUrl": "https://updatecells.pydio.com/",
    "publicKey": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"
  }
},
"services": { "pydio.grpc.update": { "channel": "stable" } }

• updateUrl + publicKey：官方更新源与更新包验签公钥（签名校验，勿改）；
• services/pydio.grpc.update/channel：更新通道，实测默认 stable（5.3 节 roundtrip 实测演示过改为 STABLE 再还原，值原样存储）。

defaults/telemetry 四个子项 metrics.readers / profiling.publishers / tracing.outputs / otelService（实测默认均为空数组或 name: cells、attributes.deployment: local），用于外发指标/剖析/追踪数据，默认不采集外发。

5.6 认证客户端参数（pydio.web.oauth）

实测 services/pydio.web.oauth 段定义了 OAuth2 认证服务：connectors（内置 pydio 连接器）、cors.public.allowedOrigins: "*"、insecureRedirects: ["#insecure_binds...#/auth/callback"]（HTTP 绑定下的回调放行占位符）、staticClients 内置四个客户端：

四个客户端的 scope 统一为 openid email profile pydio offline。排障登录回调问题时先检查本段 redirect_uris 与站点绑定是否一致。

5.7 全文搜索参数

实测 services/pydio.grpc.search：

{
  "basenameAnalyzer": "standard",
  "contentAnalyzer": "en",
  "contentRef": "pydio:ContentRef",
  "indexContent": false,
  "plainTextExtensions": "txt,md"
}

默认只索引文件名（indexContent: false）。要开启内容搜索：改 indexContent: true 并按需扩充 plainTextExtensions（内容分析器默认英文 en），改后重启服务并等待索引重建。

5.8 内置数据库驱动段

databases 段除主库外还有两个内置驱动定义（实测原文）：bleve（全文索引，bleve://{{ autoMkdir (serviceDataDir .Service) }}/{{ .Meta.file }}）与 boltdb（bolt 驱动本地 KV，DSN 结构同源）——二者以服务数据目录落盘，不需要外部数据库，是各微服务「自带小库」的默认选择。

5.9 versions 段（只读）

顶层 versions 段记录 28 个内部服务在当前配置下的版本（实测全部为 5.1.0，含 pydio.grpc.acl、pydio.grpc.jobs、pydio.grpc.meta、pydio.grpc.policy、pydio.rest.share、pydio.web.statics 等）。该段由系统维护，排障时用来核对各服务是否随主程序一起升级，不要手工编辑。

5.10 YAML/JSON 安装模型键

非交互安装（安装指南方案 B）的配置文件键与交互向导一一对应，YAML 键为官方 InstallConfig 模型字段的小写形式（来源：docs.pydio.com《YAML/JSON Installation》InstallConfig proto，查询日期 2026-10-22；实测可用键）：

六、生产配置模板

以下模板汇总一套可落地的关键段取值（自签名 TLS 换成自备证书、内容搜索开启、更新通道 stable），其余保持安装产物默认：

{
  "defaults": {
    "sites": [
      {
        "Binds": ["0.0.0.0:443"],
        "ReverseProxyURL": "https://files.example.com",
        "TLSConfig": {
          "Certificate": {
            "CertFile": "/var/cells/certs/fullchain.pem",
            "KeyFile": "/var/cells/certs/privkey.pem"
          }
        },
        "SSLRedirect": true
      }
    ]
  },
  "frontend": {
    "plugin": { "core.pydio": { "APPLICATION_TITLE": "Files", "DEFAULT_LANGUAGE": "zh-cn" } }
  },
  "services": {
    "pydio.grpc.search": { "indexContent": true, "plainTextExtensions": "txt,md,csv,log" },
    "pydio.grpc.update": { "channel": "stable" }
  }
}

配套的非配置项检查清单：systemd 单元保持 LimitNOFILE=65536 与 Environment=CELLS_WORKING_DIR=/var/cells（官方模板值）；MariaDB max_connections 调至 1000（安装指南 4.2 节实测方法）；备份 /var/cells/cells-vault-key、pydio-vault.json、frontend/session/secureKey、defaults/personalTokens/secureKey 四类密钥。每次改完执行 systemctl restart cells 并用 cells admin config check 确认配置有效。

七、常见问题

Q1：手工改了 pydio.json 不生效。 文件配置在进程启动时加载，改后必须 systemctl restart cells；或改用 cells admin config set（文件+数据库双写，下一次对应服务读取即生效）。

Q2：cells admin config history 报 no revisions store found。 file 配置存储不带修订库，属正常现象（3.2 节实测）。需要变更审计时把配置存储迁到支持修订的后端（cells admin config copy 可在存储间迁移），或以外部方式备份 pydio.json。

Q3：DSN 里的 {{.Meta.prefix}} 是什么，能删吗？ 是 Go template 运行期变量（表前缀/策略/单复数），由系统求值，删掉会导致建表异常。手工构造 DSN 时保留原样即可。

Q4：config set 后 list 显示的值大小写变了。 值原样存储（实测 stable→STABLE 后 list 即显示 STABLE），参数名才是大小写敏感的路径键。改回时重设原值。

Q5：站点证书想换正式证书。 按 5.2 节改 TLSConfig 为 Certificate 形态并填证书/私钥路径，或直接 cells configure sites 向导选择 Let's Encrypt；改后重启并清浏览器缓存验证。

Q6：想换文件存储目录或上 S3。 本地目录：改 5.3 节各 StorageConfiguration.folder 与对象服务 LocalFolder 并迁移磁盘数据后重启；S3：用 5.10 节 dss3* 键重跑非交互安装最干净（新环境），存量环境用 cells admin datasource 系列命令迁移（命令清单见后续 CLI 命令详解篇）。

Q7：管理界面语言想默认中文。 cells admin config set frontend/plugin/core.pydio DEFAULT_LANGUAGE '"zh-cn"' 后重启（值必须 JSON 编码，字符串要带引号）；等价地编辑 pydio.json 的 frontend/plugin/core.pydio/DEFAULT_LANGUAGE。

八、参考链接

• 官方文档《YAML/JSON Installation》（安装模型键）：https://docs.pydio.com/latest/admin-guide/advanced/yaml-json-installation/
• 官方知识库《Install Cells on Debian/Ubuntu》（目录布局与 systemd 单元）：https://docs.pydio.com/latest/knowledge-base/deployment/install-cells-on-debian-ubuntu/
• 官方管理文档（管理面板能力总览）：https://docs.pydio.com/latest/admin-guide/
• 站内相关文档：《Ubuntu 22.04 安装 Pydio Cells 指南》、《Pydio Cells 介绍与选型指南》