ryot v10.5.6 配置参数详解

目标：逐项讲清 ryot v10.5.6 的全部环境变量体系（服务核心、用户认证、OIDC/SMTP、前端、调度、S3 文件存储、19 个外部数据源密钥），并以运行中实例的免认证端点 /backend/config 实测输出为默认值依据。本文参数与默认值均取自 http://127.0.0.1:8141 的真实服务与官方文档 docs.ryot.io/configuration（2026-10-25 更新版）。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• ryot 版本：v10.5.6（coreDetails.version 实测回显见 3.2 节）
• 依赖数据库：PostgreSQL 18（官方要求 ≥ 15）
• 服务地址：http://127.0.0.1:8141（内部由反向代理统一入口，GraphQL 后端进程监听 5000、前端进程监听 3000）
• 部署方式：环境变量注入，无外部配置文件；部署步骤见 《ryot Docker Compose 部署指南》

二、前置条件

1. ryot 服务已启动并可访问：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8141/health
# HTTP 200

2. 具备 curl 与 JSON 工具（本文用 python3 -m json.tool 格式化输出）。
3. 需要调用 GraphQL 的章节已持有 API 令牌（获取方式见 3.2 节与 API 使用篇）。

三、参数查看与修改方式

3.1 修改方式：环境变量注入

ryot 的所有配置均为 @env 风格环境变量，在服务的启动环境中注入（如 Compose 编排的 environment: 段）。修改后需重启服务进程生效——配置在进程启动时一次性读取。

3.2 查看方式一：免认证配置端点 /backend/config

curl -s http://127.0.0.1:8141/backend/config | python3 -m json.tool

实测返回全量配置 JSON（共 121 行，节选首尾）：

{
    "books": {
        "hardcover": {
            "api_key": "<empty>"
        },
        "openlibrary": {
            "cover_image_size": "M"
        },
        ...（输出节选，实测首尾）
    },
    "server": {
        "pro_key": "<empty>",
        "oidc": { "client_id": "<empty>", "issuer_url": "", "client_secret": "<empty>" },
        "smtp": { "user": "<empty>", "server": "", "password": "<empty>", "mailbox": "Ryot <no-reply@ryot.io>" },
        "backend_port": 5000,
        "backend_host": "0.0.0.0",
        "is_demo_instance": false,
        "max_file_size_mb": 70,
        "importer": { "trakt_client_id": "<empty>" },
        "cors_origins": [],
        "admin_access_token": "****",
        "disable_background_jobs": false,
        "progress_update_threshold": 2,
        "graphql_playground_enabled": true,
        "sleep_before_startup_seconds": 0
    },
    ...（输出节选，实测首尾）
    "tz": "Etc/GMT",
    "disable_telemetry": false
}

要点：敏感值统一掩码——未设置的显示 <empty>，已设置的显示 ****，因此该端点可安全开放给内网排障使用。

3.3 查看方式二：GraphQL coreDetails

curl -s http://127.0.0.1:8141/backend/graphql -H 'Content-Type: application/json' \
  -d '{"query":"query { coreDetails { version pageSize docsLink repositoryLink signupAllowed disableTelemetry } }"}'
# {"data":{"coreDetails":{"version":"v10.5.6","pageSize":20,"docsLink":"https://docs.ryot.io","repositoryLink":"https://github.com/ignisda/ryot","signupAllowed":true,"disableTelemetry":false}}}

coreDetails 免认证可查，返回前端渲染所需的公开配置（版本号、分页大小、注册开关等 24 个字段）。

四、参数总览

按配置域分组（与 /backend/config 的 JSON 结构一一对应）：

五、核心参数分类详解

5.1 服务核心（server 域）

💡 技术拓展：TZ 取值体系有两种常见写法——IANA 时区名（Asia/Shanghai，自动处理闰秒与历史变更）与 POSIX 形式（Etc/GMT-8，注意符号相反）。本文采用 IANA 名，与官方文档示例一致。

5.2 用户与认证（users 域）

另实测：validate_password: true（默认启用密码强度校验）。注意 ryot 没有 SERVER_ADMIN_USERNAME/PASSWORD 类环境变量，管理员账号必须通过 GraphQL registerUser 携带 SERVER_ADMIN_ACCESS_TOKEN 创建。

5.3 OIDC 与 SMTP

5.4 前端（frontend 域）

5.5 调度与文件存储

5.6 数据源密钥（按媒体类型）

不配置密钥时对应数据源不可搜索，但已入库数据仍可追踪；ANILIST 等少数源免密钥可用（实测）。

六、生产配置模板

适用场景：2 vCPU / 4GB 内存 / 50GB SSD，家庭自托管 ≤5 用户，影视+动漫追踪。以 Compose environment: 段呈现（部署流程见 《ryot Docker Compose 部署指南》）：

environment:
  - DATABASE_URL=postgres://ryot:强密码替换此值@ryot-db:5432/ryot
  - SERVER_ADMIN_ACCESS_TOKEN=强随机串替换此值
  - TZ=Asia/Shanghai
  - DISABLE_TELEMETRY=true
  - FRONTEND_URL=https://ryot.example.com
  - SERVER_GRAPHQL_PLAYGROUND_ENABLED=false
  - USERS_ALLOW_REGISTRATION=false
  - SERVER_SMTP_HOST=smtp.example.com
  - SERVER_SMTP_USER=notify@example.com
  - SERVER_SMTP_PASSWORD=邮箱密码替换此值
  - MOVIES_AND_SHOWS_TMDB_ACCESS_TOKEN=TMDB令牌替换此值

逐项要点：时区保证日历与追番提醒正确；关闭遥测与 Playground 收敛信息面；关闭自助注册后由管理员建号；SMTP 用于到期提醒；TMDB 令牌覆盖影视搜索主源。

七、常见问题（FAQ）

Q1：改了环境变量为什么不生效？

配置仅在进程启动时读取，修改后必须重启服务进程；随后用免认证端点核对实际生效值：

curl -s http://127.0.0.1:8141/backend/config | python3 -m json.tool | grep -A1 '"tz"'
#         "tz": "Etc/GMT",

上例说明当前进程仍是默认时区，重启注入 TZ 后此处应变为 Asia/Shanghai。

Q2：/backend/config 会泄露密码吗？

敏感项统一掩码：未设置显示 <empty>、已设置显示 ****（实测 admin_access_token、database.url 均为 ****），可放心用于内网排障；但仍建议不暴露到公网。

Q3：想彻底关闭对作者实例的统计上报？

设 DISABLE_TELEMETRY=true。实测默认值 disable_telemetry: false，且 frontend.umami.script_url 指向作者自建 Umami 实例（见 5.4 节），关闭后前端不再加载该脚本。

Q4：GraphQL 查询页被扫描器发现？

SERVER_GRAPHQL_PLAYGROUND_ENABLED 默认 true（实测），生产置 false 后仅保留 POST /backend/graphql 程序化入口。

八、参考链接

• 官方配置文档：https://docs.ryot.io/configuration
• 官方仓库：https://github.com/IgnisDa/ryot
• 站内：《ryot Docker Compose 部署指南》