OpenCloud 配置参数详解
OpenCloud 8.1.0 配置参数全量实测：环境变量文件与 opencloud.yaml 配置体系、从二进制提取权威变量名清单（OC_/PROXY_/IDM_/STORAGE_ 等 499 项）、全局/日志/入口/身份/存储核心参数逐项修改验证、生产配置模板与六条排障实录。
OpenCloud 配置参数详解
目标：以 OpenCloud 8.1.0 为对象，讲清其配置体系（环境变量文件、
opencloud.yaml、systemd 三层载体）与核心参数的真实行为：全局基础、日志、入口网络、管理员与演示用户、存储、服务编排与功能开关，并给出可直接套用的生产配置模板与六条排障实录。全部参数行为均于 2026-10-22 在 Ubuntu 22.04 服务器上逐项修改、重启、验证，输出逐行照抄；仅收录于变量名清单、未单独复测的参数均已明确标注。
一、环境信息
本章列出实测环境的软件与路径信息，后文所有命令均在此环境执行并可复现。
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04（x86_64） |
| OpenCloud 版本 | 8.1.0（Edition: rolling，2026-10-05 编译） |
| 安装方式 | 官方单二进制 + systemd 托管（安装过程见本专栏《Ubuntu 22.04 安装 OpenCloud 指南》） |
| 二进制路径 | /usr/local/bin/opencloud |
| 环境变量文件 | /etc/opencloud/opencloud.env |
| 运行时配置 | /etc/opencloud/config/opencloud.yaml（opencloud init 生成，131 行） |
| 数据目录 | /var/lib/opencloud |
| systemd 单元 | /etc/systemd/system/opencloud.service |
| 对外访问地址 | https://10.89.56.2:9200（唯一对外入口） |
| 管理员账号 | admin / q1w2e3r4 |
二、前置条件
2.1 已完成 OpenCloud 安装
本文假设 OpenCloud 8.1.0 已按《Ubuntu 22.04 安装 OpenCloud 指南》完成安装：二进制就位、opencloud init 已初始化、systemd 服务已启用。安装篇同样给出了各配置文件的落位过程，两篇配合阅读。
2.2 确认服务处于运行状态
$ systemctl is-active opencloud
active
$ ss -ltnp | grep 9200
LISTEN 0 4096 *:9200 *:* users:(("opencloud",pid=2766,fd=190))
$ curl -sk -o /dev/null -w "%{http_code}\n" https://localhost:9200/
200
2.3 修改配置的固定套路
OpenCloud 的参数调整遵循同一套流程，本文所有实验均按此执行：
- 备份并修改
/etc/opencloud/opencloud.env（环境变量）； systemctl restart opencloud重启生效；- 用
systemctl is-active、journalctl -u opencloud、接口请求三者验证结果。
建议每次修改前先复制一份备份，便于快速回滚：
$ cp /etc/opencloud/opencloud.env /etc/opencloud/opencloud.env.bak
三、配置体系概览
3.1 三层配置载体
| 层 | 文件/位置 | 内容与定位 | 是否建议手改 |
|---|---|---|---|
| 环境变量 | /etc/opencloud/opencloud.env（由 systemd EnvironmentFile 注入） | 绝大多数行为开关与地址类参数 | 建议，运维主入口 |
| 运行时配置 | /etc/opencloud/config/opencloud.yaml | opencloud init 生成的各类密钥（jwt_secret、transfer_secret、LDAP bind_password 等）与服务级细粒度配置 | 慎改；密钥类由 init 管理即可 |
| 服务子命令 | opencloud <service> 的启动参数 | 单服务调试时使用 | systemd 全栈模式下不建议 |
三层之中，环境变量优先级直观、生效方式统一（重启服务），是本文的主线；opencloud.yaml 中的密钥在《Ubuntu 22.04 安装 OpenCloud 指南》第七章已列出目录，日常运维无需触碰。
3.2 变量命名规律：前缀即服务
OpenCloud 的环境变量按「前缀_」划分归属，记住前缀就能猜到作用域：
| 前缀 | 作用域 | 本文实测示例 |
|---|---|---|
| OC_ | 全局/跨服务 | OC_URL、OC_LOG_LEVEL、OC_INSECURE |
| PROXY_ | 入口代理服务 | PROXY_TLS、PROXY_HTTP_ADDR |
| IDM_ | 内置身份服务（idm） | IDM_ADMIN_PASSWORD、IDM_CREATE_DEMO_USERS |
| STORAGE_ | 存储服务 | STORAGE_SYSTEM_DRIVER、STORAGE_USERS_DRIVER |
| NATS_ | 内置事件总线 | NATS_NATS_HOST、NATS_NATS_PORT |
| WEB_ | Web 界面 | WEB_ 前缀主题/应用类配置 |
3.3 权威变量名清单：从二进制直接提取
文档站不可能覆盖每一个变量，最可靠的做法是直接从二进制提取变量名清单。实测命令与结果（2026-10-22，8.1.0 二进制）：
$ grep -aoE '\b(OC|PROXY|IDM|STORAGE|NATS|WEB)_[A-Z0-9_]{2,}\b' /usr/local/bin/opencloud | sort -u > /tmp/envvars.txt
$ wc -l /tmp/envvars.txt
499 /tmp/envvars.txt
各前缀数量分布：
| 前缀 | 变量数 |
|---|---|
| OC_ | 144 |
| PROXY_ | 79 |
| IDM_ | 15 |
| STORAGE_ | 178 |
| NATS_ | 17 |
| WEB_ | 66 |
若系统装有 binutils，用 strings /usr/local/bin/opencloud | grep -E '^OC_' | sort -u 可得同样结果；Ubuntu 22.04 最小安装不带 strings，grep -a 方式无需任何依赖，建议收藏。
IDM_ 前缀全部 15 个变量如下（数量少，可全量列出）：
| 变量名 | 用途 |
|---|---|
| IDM_ADMIN_PASSWORD | admin 用户初始密码（仅首次建库生效，见 7.1） |
| IDM_ADMIN_USER_ID | admin 用户 ID 覆盖 |
| IDM_CREATE_DEMO_USERS | 是否创建演示用户（见 7.2） |
| IDM_DATABASE_PATH | LDAP 库数据路径 |
| IDM_DEBUG_ADDR / IDM_DEBUG_PPROF / IDM_DEBUG_TOKEN / IDM_DEBUG_ZPAGES | 调试端点类 |
| IDM_IDPSVC_PASSWORD / IDM_REVASVC_PASSWORD / IDM_SVC_PASSWORD | 内部服务间口令（init 已写入 yaml） |
| IDM_LDAPS_ADDR / IDM_LDAPS_CERT / IDM_LDAPS_KEY | LDAPS 监听与证书 |
| IDM_LOG_LEVEL | idm 服务日志级别 |
3.4 确认变量是否真实生效
两类验证手段：
- 进程视角：
systemctl show opencloud --property=Environment可看到 EnvironmentFile 注入情况； - 行为视角：绝大多数参数改完重启后，用
journalctl -u opencloud --since "-30 seconds" --no-pager观察启动日志即可分辨（本文每个参数的实测都附带了行为证据）。
四、全局基础参数
4.1 OC_URL：全系统对外基准地址
OC_URL 是 OpenCloud 的基准 URL，idp 签发的令牌 issuer、各服务间回调、Web 端跳转都基于它拼接。必须使用 https，否则服务无法启动（排障实录见 11.1）。
$ grep OC_URL /etc/opencloud/opencloud.env
OC_URL=https://10.89.56.2:9200
改完 OC_URL 需同步检查两点：浏览器访问地址、以及引用该地址的接口（如 OIDC 发现文档 /.well-known/openid-configuration 中的 issuer 会跟随 OC_URL 变化，实测确认）。
4.2 OC_CONFIG_DIR 与 OC_BASE_DATA_PATH：两大目录锚点
| 变量 | 实测值 | 作用 |
|---|---|---|
| OC_CONFIG_DIR | /etc/opencloud/config | 存放 opencloud init 生成的 opencloud.yaml |
| OC_BASE_DATA_PATH | /var/lib/opencloud | 存放全部运行数据 |
opencloud init 与 opencloud server 都读取这两个变量，因此它们必须写入 env 文件，保证 init 和运行时落在同一目录（安装篇正是靠这两个变量实现了「配置在 /etc、数据在 /var/lib」的生产布局）。
数据目录布局实测：
$ ls /var/lib/opencloud/
idm idp nats proxy search storage
4.3 OC_INSECURE：内部 TLS 校验开关
自签证书场景保持 OC_INSECURE=true。实测改为 false 后服务依然正常运行（内部各服务使用 init 生成的自签证书互信，未受影响）：
$ sed -i "s/^OC_INSECURE=.*/OC_INSECURE=false/" /etc/opencloud/opencloud.env && systemctl restart opencloud
$ systemctl is-active opencloud
active
$ curl -sk -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/admin/
207
journal 中可见代理服务因未显式提供证书而生成临时证书的告警（该告警在 true/false 下都存在，与浏览器证书告警无关联）：
$ journalctl -u opencloud --no-pager | grep "tls certificate" | tail -1
... {"level":"warn","service":"proxy",...,"message":"No tls certificate provided, using a generated one"}
结论：OC_INSECURE 控制的是内部 TLS 校验与对 OC_URL 证书的信任；浏览器访问时的自签告警由服务端证书决定，改该变量无法消除（消除告警需替换为受信 CA 证书）。
4.4 清单收录、未单独复测的全局参数
以下变量在 3.3 节清单中确认存在，语义按官方文档与变量名自明，本文未逐项复测，列出供检索：
| 变量名 | 用途 |
|---|---|
| OC_PUBLIC_URL | 对外展示 URL（未设置时回落 OC_URL） |
| OC_ADMIN_USER_ID / OC_SYSTEM_USER_ID | 管理员与系统用户 ID 覆盖（init 已写入 yaml） |
| OC_JWT_SECRET / OC_TRANSFER_SECRET | 全局密钥（init 已写入 yaml） |
| OC_DEFAULT_LANGUAGE | 界面默认语言 |
| OC_DISABLE_PREVIEWS / OC_DISABLE_VERSIONING / OC_DISABLE_SSE | 关闭预览/版本/服务端推送 |
| OC_ENABLE_OCM | 跨实例共享（OCM）开关 |
| OC_LOG_COLOR / OC_LOG_FILE | 日志着色与落盘文件（见第五章） |
| OC_CORS_* | 跨域策略组 |
| OC_CACHE_* / OC_EVENTS_* | 缓存与事件总线连接参数组 |
| OC_GRPC_* | 内部 gRPC 通信参数组 |
五、日志参数
5.1 OC_LOG_LEVEL：日志级别
默认 info。实测改为 debug 后，journal 输出变为 JSON 行，level 字段出现 debug：
$ sed -i "s/^OC_LOG_LEVEL=.*/OC_LOG_LEVEL=debug/" /etc/opencloud/opencloud.env && systemctl restart opencloud
$ journalctl -u opencloud --since "-15 seconds" --no-pager | head -3
Oct 22 04:07:00 opencloud opencloud[3269]: {"level":"debug","service":"nats","time":"2026-10-22T04:07:00Z","line":"github.com/opencloud-eu/opencloud/services/nats/pkg/logging/nats.go:45","message":"127.0.0.1:45582 - cid:94 - \"v1.54.0:go\" - Client Ping Timer"}
Oct 22 04:07:00 opencloud opencloud[3269]: {"level":"debug","service":"nats","time":"2026-10-22T04:07:00Z","line":"github.com/opencloud-eu/opencloud/services/nats/pkg/logging/nats.go:45","message":"127.0.0.1:45588 - cid:95 - \"v1.54.0:go:jsoncs3-share-manager\" - Client Ping Timer"}
Oct 22 04:07:00 opencloud opencloud[3269]: {"level":"debug","service":"nats","time":"2026-10-22T04:07:00Z","line":"github.com/opencloud-eu/opencloud/services/nats/pkg/logging/nats.go:45","message":"127.0.0.1:45636 - cid:99 - \"v1.54.0:go:openc:3269:postprocessing:bus\" - Client Ping Timer"}
级别取值与生产建议：
| 级别 | 建议场景 |
|---|---|
| error / fatal | 极安静，仅错误（排查已知问题收窄输出时用） |
| warn | 稳定运行期可选 |
| info | 生产默认 |
| debug | 排障临时开启，日志量显著放大，用完改回 |
5.2 OC_LOG_PRETTY：JSON 换人话
OpenCloud 默认输出 JSON 日志（便于采集），人眼阅读可开 pretty 控制台格式。实测 OC_LOG_PRETTY=true 后同一启动过程变为：
$ echo "OC_LOG_PRETTY=true" >> /etc/opencloud/opencloud.env && systemctl restart opencloud
$ journalctl -u opencloud --since "-10 seconds" --no-pager | head -4
Oct 22 04:07:17 opencloud opencloud[3305]: 2026-10-22T04:07:17Z INF running on 12 cpus host.name=opencloud line=github.com/opencloud-eu/reva/v2@v2.51.0/cmd/revad/runtime/runtime.go:160 service=frontend
Oct 22 04:07:17 opencloud opencloud[3305]: 2026-10-22T04:07:17Z INF registering external service eu.opencloud.web.frontend-8dfe32d9-511f-4156-a19e-151ea1f19333@127.0.0.1:9140 line=github.com/opencloud-eu/opencloud/pkg/registry/register.go:19 service=frontend
Oct 22 04:07:17 opencloud opencloud[3305]: 2026-10-22T04:07:17Z DBG skipping auth host.name=opencloud line=github.com/opencloud-eu/reva/v2@v2.51.0/internal/grpc/interceptors/auth/auth.go:122 method=/cs3.gateway.v1beta1.GatewayAPI/Authenticate pkg=rgrpc service=storage-system traceid=613fa40920347cfc0e7b94c086a4c968
Oct 22 04:07:17 opencloud opencloud[3305]: 2026-10-22T04:07:17Z DBG serving endpoint host.name=opencloud line=github.com/opencloud-eu/reva/v2@v2.51.0/internal/http/services/owncloud/ocs/ocs.go:166 method=GET middlewares=1 pkg=rhttp route=/v{version:(1|2)}.php/apps/files_sharing/api/v1/sharees service=ocs
两种形态的级别字段对照（实测归纳）：
| 形态 | 触发变量 | 级别写法 |
|---|---|---|
| JSON | 默认 | "level":"debug"/"info"/"warn"/"error"/"fatal" |
| 控制台 | OC_LOG_PRETTY=true | INF/DBG/WRN/ERR |
5.3 OC_LOG_COLOR 与 OC_LOG_FILE
两者均在 3.3 清单中确认存在：OC_LOG_COLOR 控制控制台模式着色，OC_LOG_FILE 指定日志落盘文件路径（不设置则只进 journal/stdout）。生产建议维持默认（JSON 进 journal），由集中采集器统一处理，本文未单独复测。
六、入口与网络参数
6.1 PROXY_TLS：对外是否启用 https
proxy 是唯一对外入口。实测 PROXY_TLS=false 后 9200 变为纯 http（https 握手直接失败）：
$ sed -i "s/^PROXY_TLS=.*/PROXY_TLS=false/" /etc/opencloud/opencloud.env && systemctl restart opencloud
$ systemctl is-active opencloud
active
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9200/
200
$ curl -sk -o /dev/null -w "%{http_code}\n" https://localhost:9200/
000
恢复 PROXY_TLS=true 后 https 恢复 200。注意：PROXY_TLS=false 时 OC_URL 仍必须是 https 形式（见 11.1），两者是独立约束——一个管实际监听，一个管令牌 issuer 合法性。
6.2 PROXY_HTTP_ADDR：入口监听地址（不建议改）
变量形态是 地址:端口（清单中确认不存在 PROXY_HTTP_PORT 这类单独端口变量）。实测把它从默认的 0.0.0.0:9200 挪到 9210 时出现两种 fatal（详见 11.2），结论是：内部服务默认占用 127.0.0.1 上自 9140 起的连续端口段，proxy 入口必须整体避开，生产保持默认 9200 即可。
6.3 端口全景：一个对外，其余全是内部
服务运行时的监听实测（ss -ltnp | grep opencloud 节选）：
| 端口 | 绑定地址 | 角色 |
|---|---|---|
| 9200 | *:9200 | 唯一对外入口（proxy，Web/DAV/Graph/OIDC 全走这里） |
| 9250 | 127.0.0.1 | runtime/supervised 控制端口（opencloud list 默认连它） |
| 9140–9282 | 127.0.0.1 | 内部微服务（frontend 9140、storage-users 9158、app-provider 9164、graph 等） |
内部服务全部只绑 127.0.0.1，外部不可达，防火墙只需放行 9200。这一布局决定了端口规划只需管好 9200 一个。
6.4 PROXY_ENABLE_BASIC_AUTH
命令行/脚本验证用的 basic auth（curl -u admin:q1w2e3r4）依赖该开关。本文所有实测环境均设 PROXY_ENABLE_BASIC_AUTH=true（官方一键脚本同样默认开启并注明仅测试用途）；生产若只走 Web/OIDC 登录，可关闭以收窄攻击面，关闭后所有 -u 方式的 curl 验证都会 401。
七、管理员与演示用户参数
7.1 IDM_ADMIN_PASSWORD：只在首次建库时生效（重要）
这是本文最重要的实测结论：IDM_ADMIN_PASSWORD 只在 idm 服务首次初始化 LDAP 库时生效，密码随后固化在数据目录里；运行期修改该变量或改 yaml 均无效。
完整实测过程（每步都重启服务后验证，207=密码有效，401=密码无效）：
$ sed -i "s/^IDM_ADMIN_PASSWORD=.*/IDM_ADMIN_PASSWORD=Q1w2e3r4New/" /etc/opencloud/opencloud.env && systemctl restart opencloud
$ curl -sk -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/admin/
207
$ curl -sk -u admin:Q1w2e3r4New -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/admin/
401
改 opencloud.yaml 中 idm.service_user_passwords.admin_password 再重启——同样 207/401，无效。尝试 Graph API 改密接口——该接口不存在：
$ curl -sk -u admin:q1w2e3r4 -X POST https://localhost:9200/graph/v1.0/users/admin/changePassword -H "Content-Type: application/json" -d '{"password":"Q1w2e3r4New"}'
{"error":...} 404
唯一生效路径是重建 idm 数据库（stop 服务 → 移走数据目录 → 设新密码 → start）：
$ systemctl stop opencloud
$ mv /var/lib/opencloud/idm /var/lib/opencloud/idm.bak
$ systemctl start opencloud
$ curl -sk -u admin:Q1w2e3r4New -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/admin/
207
$ curl -sk -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/admin/
401
新密码生效，旧密码失效。代价必须清楚：idm 库重建会连带清空全部本地用户与组（实测旧组在新库中已不存在，删除请求返回 404），普通用户的文件数据在 storage 目录中虽未丢失，但账户需重建。生产改密请走 Web 界面的账号设置，或参考《OpenCloud 常用 CLI 命令详解》中的 Graph API 用户管理；IDM_ADMIN_PASSWORD 只用于首次部署时定好初始密码。
7.2 IDM_CREATE_DEMO_USERS：演示用户开关
设为 true（首次建库前）会在初始化时创建一批演示账号。实测清单（官方一键脚本实例中验证）：
$ curl -sk -u admin:admin "https://localhost:9200/graph/v1.0/users?\$select=displayName,onPremisesSamAccountName"
admin | Admin
alan | Alan Turing
lynn | Lynn Conway
mary | Mary Kenneth Keller
margaret | Margaret Hamilton
dennis | Dennis Ritchie
与 7.1 同理：该变量只在首次建库时起作用，事后关闭/开启都不会增删既有账号。生产环境保持默认 false，不要带演示账号上线。
八、存储参数
8.1 存储驱动：STORAGE_SYSTEM_DRIVER 与 STORAGE_USERS_DRIVER
| 变量 | 作用 | 实测状态 |
|---|---|---|
| STORAGE_SYSTEM_DRIVER | 系统存储（配置、元数据）驱动 | 默认 decomposedfs，未切换复测 |
| STORAGE_USERS_DRIVER | 用户文件存储驱动 | 默认 decomposedfs，未切换复测 |
OpenCloud 内置 decomposedfs（把元数据存为文件系统上的对象，无外部数据库）与 posixfs（直接利用 POSIX 目录树）两类驱动。8.1.0 单二进制默认开箱即用 decomposedfs，本文未做切换实测；生产若想用既有目录树可评估 posixfs（配套运维命令见《OpenCloud 常用 CLI 命令详解》中的 opencloud posixfs 子命令组）。
8.2 OC_DECOMPOSEDFS_PROPAGATOR
decomposedfs 的变更传播器类型，清单中确认存在；默认值即可满足单机部署，本文未复测。
8.3 数据目录布局
OC_BASE_DATA_PATH=/var/lib/opencloud 下实测布局：
$ ls /var/lib/opencloud/
idm idp nats proxy search storage
| 子目录 | 归属服务 | 内容 |
|---|---|---|
| idm | 身份服务 | 内置 LDAP 库（账号/组；见 7.1 重建实验） |
| idp | 认证服务 | OIDC 会话与密钥 |
| nats | 事件总线 | 内嵌 NATS 持久化 |
| proxy | 入口代理 | 会话/证书状态 |
| search | 全文搜索 | 索引 |
| storage | 文件存储 | decomposedfs 元数据与 blob |
备份策略应覆盖整个 /var/lib/opencloud（离线冷备为主，运行中直接拷贝存在一致性风险）。
九、服务编排与功能开关
9.1 OC_EXCLUDE_RUN_SERVICES / OC_ADD_RUN_SERVICES
opencloud server 以 supervised 模式拉起全部内置服务，opencloud list 可看到 30 余个服务实例（完整输出见《OpenCloud 常用 CLI 命令详解》）。这两个变量用于裁剪或追加运行集，例如排除用不到的 antivirus/notifications 等服务以省资源。变量名经 3.3 清单确认存在，裁剪组合本文未逐项复测——改动后务必用 opencloud list 与核心接口（登录页、WebDAV、Graph）双重验证。
9.2 功能开关组
| 变量 | 作用 | 备注 |
|---|---|---|
| OC_DISABLE_PREVIEWS | 关闭文件预览/缩略图 | 省资源，牺牲体验 |
| OC_DISABLE_VERSIONING | 关闭文件版本历史 | 关闭后不可回溯旧版本 |
| OC_DISABLE_SSE | 关闭服务端事件推送 | 关闭后 Web 端改动需手动刷新 |
| OC_DEFAULT_LANGUAGE | 默认界面语言 | 如 zh |
| OC_ENABLE_OCM | 跨实例共享开关 | 多实例联邦场景才需要 |
以上均在清单中确认存在，语义明确，本文未逐项复测；开关类参数按需启用并回归验证核心链路即可。
9.3 密码策略组 OC_PASSWORD_POLICY_*
清单提取到 7 个：
$ grep -E '^OC_PASSWORD_POLICY' /tmp/envvars.txt
OC_PASSWORD_POLICY_BANNED_PASSWORDS_LIST
OC_PASSWORD_POLICY_DISABLED
OC_PASSWORD_POLICY_MIN_CHARACTERS
OC_PASSWORD_POLICY_MIN_DIGITS
OC_PASSWORD_POLICY_MIN_LOWERCASE_CHARACTERS
OC_PASSWORD_POLICY_MIN_SPECIAL_CHARACTERS
OC_PASSWORD_POLICY_MIN_UPPERCASE_CHARACTERS
用于约束用户设置密码的复杂度（最小长度/数字/大小写/特殊字符与禁用密码表），生产建议至少设置 MIN_CHARACTERS 与 MIN_DIGITS。
十、生产配置模板
10.1 /etc/opencloud/opencloud.env 模板
以下即本文实测环境使用的完整文件，可直接套用（替换 OC_URL 中的地址）：
# OpenCloud 全局基础
OC_CONFIG_DIR=/etc/opencloud/config
OC_BASE_DATA_PATH=/var/lib/opencloud
OC_URL=https://10.89.56.2:9200
OC_INSECURE=true
OC_LOG_LEVEL=info
# 入口 proxy
PROXY_TLS=true
# 管理员与演示数据
IDM_ADMIN_PASSWORD=q1w2e3r4
# 命令行验证用（生产可关闭）
PROXY_ENABLE_BASIC_AUTH=true
要点回顾：
- OC_URL 必须 https（11.1）；
- IDM_ADMIN_PASSWORD 在首次
opencloud init/建库前确定，之后不再改动（7.1）； - OC_INSECURE=true 仅匹配自签场景，接入受信 CA 证书后应改回 false；
- 生产可追加 OC_LOG_PRETTY=false（默认即 JSON）、按需追加第九章开关。
10.2 systemd 单元模板
[Unit]
Description=OpenCloud file sharing platform
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
Group=root
EnvironmentFile=/etc/opencloud/opencloud.env
ExecStart=/usr/local/bin/opencloud server
Restart=on-failure
RestartSec=5
TimeoutStopSec=90
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
Restart=on-failure 与 RestartSec=5 的组合在实践中很重要：参数写错导致服务崩溃时，systemd 会反复重启并在 journal 留下完整 fatal 信息，恰好是排障的一手材料（见第十一章）。
10.3 变更后的验证清单
$ systemctl restart opencloud && systemctl is-active opencloud
active
$ curl -sk -o /dev/null -w "%{http_code}\n" https://localhost:9200/
200
$ curl -sk -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" -X PROPFIND -H "Depth: 0" https://localhost:9200/remote.php/dav/files/admin/
207
$ journalctl -u opencloud --since "-30 seconds" --no-pager | grep -c '"level":"fatal"'
0
四项全绿（active、200、207、无 fatal）才算变更闭环。
十一、常见问题与排障实录
11.1 Q1：OC_URL 写成 http 后服务起不来
现象：把 OC_URL 改为 http://10.89.56.2:9200 后，服务进入 activating 反复重启：
$ systemctl is-active opencloud
activating
$ journalctl -u opencloud --no-pager | grep error | tail -1
... {"level":"error","service":"storage-users",...,"message":"Disconnected from NATS. Trying to reconnect..."}
前台运行捕获到根因（真实输出）：
{"level":"fatal","service":"idp","error":"invalid iss value, URL must start with https://","time":"2026-10-22T04:08:51Z","line":"github.com/opencloud-eu/opencloud/services/idp/pkg/service/v0/service.go:122","message":"could not bootstrap idp"}
结论：idp 服务的 issuer 校验强制要求 https，OC_URL 是硬约束，只能用 https://。改回 https 后恢复正常。
11.2 Q2：想把入口从 9200 挪到别的端口，结果起不来
现象一：仅改 PROXY_HTTP_ADDR=0.0.0.0:9210（OC_URL 保持 :9200）→ activating，前台 fatal：
{"level":"fatal","service":"opencloud","event":"opencloud: Failed service 'proxy' (5.999235 failures of 5.000000), restarting: false, panic: config: Cannot set options after data has been loaded, ...（panic 发生在 proxy loadCSPConfig）...","message":"service panic"}
现象二：OC_URL 与 PROXY_HTTP_ADDR 同步改为 9210 → 换了一个 fatal：
{"level":"fatal","service":"opencloud","event":"opencloud: Failed service 'userlog' (5.998868 failures of 5.000000), restarting: false, error: listen tcp 127.0.0.1:9210: bind: address already in use","service":"userlog",...}
结论：OpenCloud 内部服务默认占用 127.0.0.1 自 9140 起的连续端口段，9210 与内部服务冲突；proxy 入口改端口需要整体重排全部服务端口，收益极低。生产保持默认 9200 入口，用反向代理/防火墙做对外映射。
11.3 Q3：改了 IDM_ADMIN_PASSWORD 却不生效
完整实测与结论见 7.1：该变量仅首次建库生效；运行期改变量、改 yaml、调 changePassword 接口（404）三条路全部无效；重建 idm 数据目录可生效但会清空全部本地账号与组。生产改密走 Web 界面。
11.4 Q4：日志看不懂/太吵
- 想要人话日志：
OC_LOG_PRETTY=true（5.2，实测 INF/DBG 控制台格式）； - 想要更细排障：
OC_LOG_LEVEL=debug（5.1，实测 JSON debug 行），用完记得改回 info； - journal 里按级别过滤：
journalctl -u opencloud --no-pager | grep '"level":"error"'。
11.5 Q5：OC_INSECURE=false 会怎样
实测服务照常运行、内部互信不受影响（4.3），浏览器自签告警依旧——该告警由服务端证书决定，与该变量无关。消除告警的正确路径是部署受信 CA 签发的证书。
11.6 Q6：想确认某个功能由哪个变量控制
直接从二进制捞变量名（3.3 的命令），再按前缀定位归属。例如怀疑预览相关行为，捞到 OC_DISABLE_PREVIEWS 即可定点验证。该方法不依赖任何外部文档，版本升级后变量有增删也能第一时间发现。
十二、参考链接
- 官方管理文档：https://docs.opencloud.eu/docs/admin/
- 官方仓库与版本发布页：https://github.com/opencloud-eu/opencloud/releases
- 上游同源产品的参数体系对照：ownCloud oCIS 配置参数详解
- 安装与初始化过程：Ubuntu 22.04 安装 OpenCloud 指南
- 服务运维与用户管理操作：OpenCloud 常用 CLI 命令详解
- 认知与选型背景：OpenCloud 介绍与选型指南