yarn.social v0.16.0 配置参数详解

yarnd v0.16.0 三层配置模型（flag > 环境变量 > config.yml）实测优先级、60+ 参数逐项分组详解：store 绝对路径大坑、三枚 64 位密钥、注册策略与镜像默认值差异、抓取后台任务、TLS/SMTP/限额、生产 compose 模板与配置问题速查表。

yarn.social自托管FediverseGo去中心化2026/11/02

yarn.social v0.16.0 配置参数详解

本文逐项拆解 yarnd v0.16.0（构建串 yarnd 0.16.0@1e81cc4e go1.26.5）的配置体系：命令行 flag、环境变量、config.yml 文件三层模型与优先级、各参数组的生产取值建议。所有实测输出来自真实 Pod 启动回显，逐行照抄；参数清单以 yarnd --help 实测输出为准。部署过程见 《yarn.social v0.16.0 Docker Compose 部署指南》。

1. 三层配置模型与优先级

yarnd 的配置来源按优先级从高到低：

  1. 命令行 flag（yarnd --help 可列全部 60+ 项）；
  2. 环境变量：规则为"长选项名全大写、连字符换下划线"（官方 README 明示），如 --name → NAME、--cookie-secret → COOKIE_SECRET、--fetch-interval → FETCH_INTERVAL；
  3. 实例配置文件：--config 指定路径，默认 <data>/config.yml——即 Setup 向导生成的那份。

flag 与环境变量的优先级实测（同一实例同时给 NAME=env-name 与 -n flag-name）：

# docker run --rm -e NAME=env-name -v .../data:/data prologic/yarnd:latest yarnd -d /data -s bitcask:///data/yarn.db --skip-setup -n flag-name -b 0.0.0.0:8000
time="2026-11-02T10:50:33Z" level=info msg="Instance Name: flag-name"

只给环境变量时（NAME=env-pod-demo，不带 -n）：

time="2026-11-02T10:50:14Z" level=info msg="Instance Name: env-pod-demo"

结论：flag > env，两者都未给时落到 config.yml / 内置默认值。官方 README 建议"多数配置用环境变量完成"，编排场景把 flag 写进 command:、密钥写进 environment:/.env 是两种主流做法，勿混用同一参数以免掩盖真实生效值。

2. 实例身份与网络

参数环境变量默认值说明
-n, --nameNAMEyarn.localPod 名称，出现在页面标题、logo 与 feed 头注释
-m, --descriptionDESCRIPTION官方长句Pod 描述（meta description / About 页）
-u, --base-urlBASE_URLhttp://0.0.0.0:8000公网基址，feed 头、avatar URL、metrics 日志均按它渲染；反代/TLS 场景必须改成对外 https 地址
-b, --bindBIND0.0.0.0:8000监听地址:端口（[int]:<port> 语法亦可绑指定网卡）
--tlsTLSfalse内置 TLS 开关
--tls-cert / --tls-keyTLS_CERT / TLS_KEY空留空则自动走 Let's Encrypt 签发

启动日志会完整回显生效配置，是核对优先级的第一现场：

time="2026-11-02T10:49:15Z" level=info msg="serving metrics endpoint at http://127.0.0.1:8129/metrics"
time="2026-11-02T10:49:15Z" level=info msg="Instance Name: yarn.local"
time="2026-11-02T10:49:15Z" level=info msg="Base URL: http://127.0.0.1:8129"
time="2026-11-02T10:49:15Z" level=warning msg="No TLS configured"

3. 数据与存储

参数环境变量默认值说明
-d, --dataDATA./data数据目录：config.yml、feeds/、cache.db*、yarn.db/、peers.json 全在此
-s, --storeSTOREbitcask://yarn.db主存储 URI，内嵌 Bitcask KV
--configCONFIG<data>/config.yml实例配置文件路径

实测大坑（务必绝对路径）：-s bitcask://yarn.db 的相对路径按进程工作目录解析（官方镜像 WORKDIR 为 /），与 -d 无关，导致：

time="2026-11-02T10:48:40Z" level=error msg="error creating store" error="mkdir yarn.db: permission denied"
time="2026-11-02T10:48:40Z" level=fatal msg="error creating server" error="mkdir yarn.db: permission denied"

正确写法是官方 README 示例的三斜杠绝对形式：-s bitcask:///data/yarn.db。另注意 Bitcask 独占加锁，同一数据目录起第二个实例会 error: database locked 直接 fatal。

数据目录实测结构（Pod 运行两天内）：

# ls -la data/
-rw-r--r-- 1 yahui yahui   4096 cache.db          # 关注源缓存（SQLite）
-rw-r--r-- 1 yahui yahui  32768 cache.db-shm
-rw-r--r-- 1 yahui yahui 346112 cache.db-wal
-rw------- 1 yahui yahui    175 config.yml        # 向导生成，0600
drwxr-xr-x 2 yahui yahui   4096 feeds/            # 每用户一个纯文本 feed
-rw-r--r-- 1 yahui yahui      3 followers.json
-rw-r--r-- 1 yahui yahui      5 peers.json
-rw-r--r-- 1 yahui yahui     18 websub.json
drwx------ 2 yahui yahui   4096 yarn.db/          # Bitcask 主存储

4. 安全密钥与会话

参数环境变量默认值
--cookie-secretCOOKIE_SECRETINVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE
--magiclink-secretMAGICLINK_SECRET同上字面量
--api-signing-keyAPI_SIGNING_KEY同上字面量
--session-expirySESSION_EXPIRY240h0m0s
--session-cache-ttlSESSION_CACHE_TTL1h0m0s
--api-session-timeAPI_SESSION_TIME240h0m0s（API token 有效期）
-a, --authAUTHsession（可选 proxy）
--auth-headerAUTH_HEADERX-User（proxy 模式下前置网关传用户名所用头）

官方 README 硬性要求：生产实例（不带 -D/--debug）必须配置三个 64 字符随机密钥，生成方式实测：

# cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1
9oawILICDTBIj4GdUcq141FE7WLQqslPzrzJcCDInZwTI2NZ3JW4qG9E2ndn2dkl

（仓库另有现成脚本 ./tools/gen-secrets.sh，输出可直接粘进 compose。密钥只经环境变量注入，README 明令勿写入共享文件。）三个密钥分别守护：会话 Cookie、密码找回 magic link、API token 签名——任一保持默认值即等于没设防。

5. 注册与可见性策略

参数环境变量语义
-R, --open-registrationsOPEN_REGISTRATIONS开放注册
-I, --invite-onlyINVITE_ONLY仅邀请注册（用户可申请邀请）
-O, --open-profilesOPEN_PROFILES用户主页对外开放
--front-pageFRONT_PAGE匿名首页行为，默认 local（可设 discover 展示全网发现流）
-E/-N/-A, --admin-email/name/userADMIN_*默认管理账号三件套（admin/Administrator/support@yarn.social）

实测注意：官方 README 称裸二进制"注册默认关闭"，但官方镜像启动日志实测默认 Open Registrations: true（两次冷启动日志一致）：

time="2026-11-02T10:50:14Z" level=info msg="Open Registrations: true"

镜像入口脚本与裸二进制默认值存在差异，生产上线以启动日志回显为准，并显式写 -R/-I 固定策略，勿依赖默认。注册表单本身带 PoW 工作量证明（pow_challenge/pow_difficulty，难度 16 bit）与蜜罐字段 pooh，实测求解难度极低（毫秒级），对真人浏览器无感、对脚本灌水有效。

6. 内容限额

参数默认值说明
-L, --max-twt-length1024单条 twt 字节上限（twtxt 传统短文本定位）
-S, --max-feed-size524288feed 文件超过 512KB 触发轮转（RotateFeeds 任务）
-F, --max-fetch-limit1048576抓取远端 feed 的字节上限 1MB
-U, --max-upload-size16777216媒体上传上限 16MB
--max-age-days10缓存 twt 最大保留天数
-T, --twts-per-page50时间线分页条数

7. 抓取与缓存（pull 模型的发动机）

参数默认值说明
--fetch-interval@every 5m关注源刷新 cron 表达式（robfig/cron 语法）
--max-cache-fetchers6抓取工作协程数
--queue-buffer-size—抓取队列缓冲

启动日志实测回显的后台任务全景（与配置联动）：

time="2026-11-02T10:39:21Z" level=info msg="Started background job UpdateFeeds (@every 5m)"
time="2026-11-02T10:39:21Z" level=info msg="Started background job ConvergeFeeds (@every 5m)"
time="2026-11-02T10:39:21Z" level=info msg="Started background job ActiveUsers (@hourly)"
time="2026-11-02T10:39:21Z" level=info msg="Started background job DeleteOldSessions (@hourly)"
time="2026-11-02T10:39:21Z" level=info msg="Started background job RotateFeeds (0 0 1 * *)"
time="2026-11-02T10:39:21Z" level=info msg="Started background job SyncStore (@every 1m)"

ConvergeFeeds 负责与对等 Pod 比对修正 twt（--max-age-days 控制窗口），SyncStore 每分钟把内存态刷回 Bitcask。

8. 联邦与外部资源

参数默认值说明
--bridge-url空配置后经 Yarn.social 的 ActivityPub bridge 代理 webfinger，与 Fediverse 互通
--blocked-feedsport70\.dk,enotty\.dk,gopher\.floodgap\.com,lublin\.se禁止抓取的 feed 域名正则表
--permitted-imagesimgur\.com,giphy\.com,imgs\.xkcd\.com,reactiongifs\.com,githubusercontent\.com允许内联展示图片的域名白名单
--disable-media / --disable-ffmpegfalse关闭媒体支持/视频转码（转码超时 --transcoder-timeout 默认 10m）

9. SMTP 与运维开关

--smtp-host/--smtp-port/--smtp-user/--smtp-pass/--smtp-from（环境变量同名大写）默认全部是 INVALID CONFIG VALUE 占位——不配则密码找回与 /support、/abuse 邮件不可用。运维侧：-D/--debug 调试日志、--log-file 落盘（默认 stderr）、--disable-logger 关访问日志、--disable-gzip 关压缩、--disable-support 关支持入口。

10. Setup 向导与 --skip-setup

无 config.yml 时全站 302 /setup；向导字段 baseURL/adminUser/adminPassword(Confirm)/podName/podDescription/dataPath/storePath，提交后生成：

# cat data/config.yml
base_url: http://127.0.0.1:8129
admin_user: admin
data: /data
store: bitcask:///data/yarn.db
pod_name: yarn.local
pod_description: Yarn.social 测试 Pod
setup_complete: true

setup_complete: true 存在即跳过向导（重启实测 GET / 直接 200）；数据目录里已有 Pod 数据时，启动日志同样会明确宣告跳过：

time="2026-11-02T10:48:44Z" level=info msg="existing pod data detected, skipping setup wizard"

--skip-setup 则无条件把实例视为"已配置"直接起服务（实测带该 flag 冷启动后全站可访问、不再 302 /setup），适合 IaC 全自动拉起。

注意向导只写上述 7 个键，密钥、限额、抓取策略均不在 config.yml 内，必须走 flag/env——这也是官方 README"多数配置用环境变量"建议的由来。

11. 生产配置模板（compose 片段）

    command:
      - yarnd
      - -d
      - /data
      - -s
      - bitcask:///data/yarn.db        # 绝对路径，血泪教训
      - -n
      - pod.example.com
      - -u
      - https://pod.example.com        # 公网基址，影响 feed 头 URL
      - -I                             # 邀请制；开放社区用 -R
      - -O
      - --fetch-interval
      - "@every 10m"
      - --cookie-secret
      - ${YARN_COOKIE_SECRET}          # 64 位随机，来自 .env
      - --magiclink-secret
      - ${YARN_MAGICLINK_SECRET}
      - --api-signing-key
      - ${YARN_API_SIGNING_KEY}
    environment:
      SMTP_HOST: smtp.example.com
      SMTP_PORT: "587"
      SMTP_USER: yarnd
      SMTP_PASS: ${SMTP_PASS}
      SMTP_FROM: pod@example.com

12. 常见配置问题速查

现象根因处置
启动即 mkdir yarn.db: permission denied 崩溃循环-s 传了相对路径，按 WORKDIR 解析改 bitcask:///data/yarn.db
error: database locked同一数据目录被第二个实例占用fuser -v data/yarn.db/* 找持锁进程，保证单实例
feed 头里 URL 是 0.0.0.0:8000未设 -u 公网基址设 -u https://域名 并重启
密码找回/举报邮件无效SMTP_* 保持占位默认值配置五枚 SMTP 参数
页面 400（脚本提交表单）CSRF 值含 HTML 实体 &#43; 未解码脚本先做实体反转义
改了 config.yml 不生效flag/env 同名参数覆盖了文件值按"flag > env > config.yml"排查

13. 相关文档

yarn.social v0.16.0 配置参数详解 - Quzuo