GoToSocial 0.22.3 配置参数详解

目标：逐组讲清 GoToSocial v0.22.3 的 config.yaml 配置体系——参数的查看方式、四级优先级、默认值与修改影响，并给出小型实例的生产配置模板。全部默认值取自官方示例配置（example/config.yaml，1661 行）与 gotosocial debug config 实测输出，覆盖内容在 Ubuntu 22.04.5 实测环境（/gotosocial、端口 8147）验证。

一、环境信息

本章说明本文参数取证与验证的环境口径。

操作系统：Ubuntu 22.04.5 LTS x86_64
软件版本：GoToSocial 0.22.3+git-5a6c8e2
安装形态：官方二进制 + systemd（安装过程见《Ubuntu 22.04 安装 GoToSocial 0.22.3 指南》）
配置文件：/gotosocial/config.yaml（最小化配置）；参数默认值参照官方包内 /gotosocial/example/config.yaml
参数取证方式：gotosocial debug config 打印生效配置（JSON，249 行）；环境变量覆盖逐项实测
验证基线：SQLite + 本地存储 + HTTP 8147 的本地实例模式

二、前置条件

已按安装指南完成 GoToSocial 部署并能启动（systemctl is-active gotosocial 为 active），同时确认版本号：

/gotosocial/gotosocial --version

实测回显：

gotosocial version 0.22.3+git-5a6c8e2

配置修改后都需要重启服务生效（官方文档明确要求）：systemctl restart gotosocial。

三、参数查看与修改方式

GoToSocial 的配置有四个入口，优先级从高到低为：命令行 flag > 环境变量 GTS_ > config.yaml > 内置默认值*。官方示例配置自带全部参数注释，是查阅默认值的第一手材料。

3.1 查看生效配置：debug config

最可靠的核查手段是 debug config，它把四个来源合并后的最终生效值以 JSON 打印（完整 249 行，下为首段实测）：

cd /gotosocial
./gotosocial --config-path ./config.yaml debug config | head -18

实测回显：

{
    "account-domain": "",
    "accounts-allow-custom-css": false,
    "accounts-custom-css-length": 10000,
    "accounts-max-profile-fields": 6,
    "accounts-reason-required": true,
    "accounts-registration-backlog-limit": 20,
    "accounts-registration-daily-limit": 10,
    "accounts-registration-open": false,
    "advanced-cookies-samesite": "lax",
    "advanced-csp-extra-uris": [],
    "advanced-header-filter-mode": "",
    "advanced-rate-limit-exceptions": null,
    "advanced-rate-limit-requests": 300,
    "advanced-sender-multiplier": 2,
    "advanced-throttling-multiplier": 8,
    "advanced-throttling-retry-after": 30000000000,
    "application-name": "gotosocial",
    "bind-address": "0.0.0.0",

注意键名与 config.yaml 中的连字符写法一一对应，排查「改了不生效」时以此输出为准。

3.2 环境变量覆盖（GTS_*）

任何配置键都可以转成大写下划线的 GTS_* 环境变量注入，适合 systemd Environment= 场景。实测覆盖 log-level 与 port：

cd /gotosocial
GTS_LOG_LEVEL=debug GTS_PORT=9999 ./gotosocial --config-path ./config.yaml debug config | grep -E '"(log-level|port)"'

实测回显：

    "log-level": "debug",
    "port": 9999,

同名规则举例：host → GTS_HOST、db-type → GTS_DB_TYPE、storage-local-base-path → GTS_STORAGE_LOCAL_BASE_PATH。systemd 单元里官方预留了 Environment= 示例（如 GTS_WAZERO_COMPILATION_CACHE），每行只写一个变量。

3.3 配置文件修改

编辑 /gotosocial/config.yaml（或 --config-path 指向的任意路径），只保留与默认值不同的项。改完重启并核对生效：

systemctl restart gotosocial
./gotosocial --config-path /gotosocial/config.yaml debug config | grep '"port"'

实测回显：

    "port": 8147,

3.4 命令行 flag

所有参数也有等价 flag 形式（--host、--port、--db-type 等，gotosocial --help 可列出全部）。flag 优先级最高，适合临时验证：

cd /gotosocial
./gotosocial --config-path ./config.yaml --port 8888 debug config | grep '"port"'

实测回显：

    "port": 8888,

💡 技术拓展：配置加载优先级是自托管软件的通用设计模式。常见实现对比——

形式代表软件特点
flag > env > 文件 > 默认 GoToSocial、Grafana 四级全开，12-factor 友好
文件 > env，无内置默认 Nginx、PostgreSQL 必须显式给全量配置
env 优先（12-factor） Mastodon 以 .env.production 为中心

GoToSocial 采用四级合并且提供 debug config 透出最终值，排障时优先用它而非猜文件。

形式	代表软件	特点
flag > env > 文件 > 默认	GoToSocial、Grafana	四级全开，12-factor 友好
文件 > env，无内置默认	Nginx、PostgreSQL	必须显式给全量配置
env 优先（12-factor）	Mastodon	以 .env.production 为中心

四、参数总览

官方示例配置的全部顶层键按功能分成 12 组，组内键名前缀即组名：

参数组	代表键	默认值要点
日志	`log-level`、`log-client-ip`、`log-format`	info / true / logfmt
通用与服务	`application-name`、`host`、`account-domain`、`protocol`、`bind-address`、`port`	localhost / 空 / https / 0.0.0.0 / 8080
数据库	`db-type`、`db-address`、`db-sqlite-*`	sqlite / sqlite.db / WAL
缓存	`cache:`（内存占比组）与 `cache-memory-target`	目标内存按宿主自动计算
Web 资源	`web-template-base-dir`、`web-asset-base-dir`	./web/template/、./web/assets/
实例与联邦	`instance-federation-mode`、`instance-expose-*`	blocklist / 全 false
账号	`accounts-registration-open`、`accounts-reason-required`	false / true
媒体	`media-local-max-size`、`media-remote-cache-duration`	40MiB / 7 days
存储	`storage-backend`、`storage-local-base-path`、`storage-s3-*`	local / /gotosocial/storage
状态	`statuses-max-chars`、`statuses-poll-max-options`	5000 / 6
TLS	`letsencrypt-enabled`、`tls-certificate-chain`	false / 空
集成与高级	`smtp-`、`oidc-`、`syslog-`、`advanced-`、`tracing-`、`metrics-`	默认关闭

关键差异解读：host/protocol/port 三个键决定实例身份与入口，是所有部署都要显式确认的；其余组大多可用默认值起步，需要动的是联邦策略（对公网实例）与媒体限制（对开放注册实例）。

五、核心参数分类详解

本章逐组拆解高频参数：语义、默认值、改动影响与实测观察。

5.1 日志参数

log-level: "info"          # debug/info/warn/error
log-db-queries: false      # 打印每条 SQL，排障用
log-client-ip: true        # 日志带客户端 IP
log-format: "logfmt"       # logfmt 或 json
log-timestamp-format: "02/01/2026 15:04:05.000"

实测说明：默认 logfmt 格式一行一条，形如 timestamp="29/10/2026 17:41:08.549" func=workers.(*Workers).Start level=INFO msg="started 24 dereference workers"；log-level: "debug" 后日志量显著增大，生产保持 info。日志同时进 stdout（systemd 场景进 journald，journalctl -u gotosocial 查看）。

5.2 服务身份参数（host/protocol/port）

host: "localhost"       # 实例主机名，账号标识的一部分，启用联邦后不可改
account-domain: ""      # 高级：把 Web 域名与账号域名解耦，默认留空=用 host
protocol: "http"        # http 或 https；示例默认 https
bind-address: "0.0.0.0" # 监听地址，IPv6 需方括号如 [::1]
port: 8080              # 示例默认 8080，本文实测改 8147

改动影响实测：protocol: "http" 启动时打印 WARN（本地实测回显）：

timestamp="29/10/2026 17:39:37.552" func=config.Validate level=WARN msg="protocol was set to 'http'; this should *only* be used for debugging and tests!"

host 是联邦身份锚点（WebFinger、actor URL 都基于它），实测本地实例的账号 URL 即 http://localhost/@admin。host 一旦有外部账号互关就不可再改，上生产前必须定型为正式域名。

💡 技术拓展：host 与 account-domain 的组合是联邦服务器的身份设计问题。主流对比——

方案代表特点
单域名 Mastodon、GoToSocial 默认 Web 与账号同一域名，简单
双域名解耦 GoToSocial account-domain、Pleroma Web 挂在 a.com，账号是 @user@b.com，迁移余地大

除非预判要换 Web 域名，否则保持默认（account-domain 留空）。

方案	代表	特点
单域名	Mastodon、GoToSocial 默认	Web 与账号同一域名，简单
双域名解耦	GoToSocial `account-domain`、Pleroma	Web 挂在 a.com，账号是 @user@b.com，迁移余地大

5.3 数据库参数

db-type: "sqlite"           # sqlite 或 postgres
db-address: "sqlite.db"     # sqlite=文件路径；postgres=主机:端口
db-port: 5432               # postgres 专用
db-user/db-password: ""     # postgres 专用
db-database: "gotosocial"
db-tls-mode: "disable"      # postgres 连接 TLS
db-max-open-conns-multiplier: 8
# SQLite 专用
db-sqlite-journal-mode: "WAL"
db-sqlite-synchronous: "NORMAL"
db-sqlite-cache-size: "8MiB"
db-sqlite-busy-timeout: "30m"

实测说明：SQLite 形态首次启动自动建库建表并跑迁移，实测日志 func=bundb.sqliteConn ... msg="connected to SQLITE database with address file:/gotosocial/sqlite.db?_pragma=busy_timeout(1800000)&_pragma=journal_mode(WAL)&..." 可见 WAL 与 30 分钟 busy_timeout 实际生效；CLI 子命令与服务进程可并发访问同一 SQLite 库（WAL 读写分离），database ping 在服务运行时实测通过。

💡 技术拓展：两款后端怎么选——

维度 SQLite PostgreSQL
部署单文件，零外部依赖独立服务，需另行安装
并发 WAL 读写并发，写单写者多连接并发写
备份拷文件（停服热备谨慎） pg_dump 生态
适用个人/小团队实例（官方默认）多用户实例、已有 PG 运维体系

官方默认且主推 SQLite；用户量大或需与既有 PG 集群统一管理时切 postgres，对应键换 db-address/user/password/database。PostgreSQL 安装与参数见《Ubuntu 22.04 安装 PostgreSQL 18 指南》、《PostgreSQL 18 配置参数详解》。

维度	SQLite	PostgreSQL
部署	单文件，零外部依赖	独立服务，需另行安装
并发	WAL 读写并发，写单写者	多连接并发写
备份	拷文件（停服热备谨慎）	pg_dump 生态
适用	个人/小团队实例（官方默认）	多用户实例、已有 PG 运维体系

5.4 实例与联邦参数

instance-federation-mode: "blocklist"   # blocklist（默认，拉黑制）/ allowlist（白名单制）
instance-federation-spam-filter: false  # 内置垃圾过滤器
instance-expose-peers: false            # 公开联邦对端列表
instance-expose-blocklist: false        # 公开拉黑列表
instance-expose-public-timeline: false  # 公开 fired 时间线（/api/v1/timelines/public）
instance-expose-custom-emojis: false    # 公开自定义表情
instance-deliver-to-shared-inboxes: true
instance-inject-mastodon-version: false # 对外版本号伪装成 Mastodon
instance-stats-mode: ""                 # 实例统计对外展示模式
instance-languages: []

实测说明：instance-expose-public-timeline: false 时，未登录访问 /api/v1/timelines/public 被拒；federation-mode 是对公网实例的核心治理开关——blocklist 默认全联通、按域拉黑，allowlist 只与白名单内实例互 federate，被官方用于「私密实例」场景。

💡 技术拓展：联邦准入策略对比——

策略语义适用
blocklist（黑名单）默认全网互通，拉黑例外公开实例、开放注册
allowlist（白名单）默认全隔离，白名单放行朋友/家庭实例、合规要求高的组织

GoToSocial 两者都支持且可运行时切换；本系列实验为本地 solo 模式，保持默认 blocklist 不影响单机功能。

策略	语义	适用
blocklist（黑名单）	默认全网互通，拉黑例外	公开实例、开放注册
allowlist（白名单）	默认全隔离，白名单放行	朋友/家庭实例、合规要求高的组织

5.5 账号参数

accounts-registration-open: false   # 是否开放注册；false=仅受邀
accounts-reason-required: true      # 注册需填申请理由
accounts-registration-daily-limit: 10      # 每 24h 通过注册上限
accounts-registration-backlog-limit: 20    # 待审队列上限，超了自动关注册
accounts-allow-custom-css: false    # 允许用户自定义 CSS
accounts-custom-css-length: 10000
accounts-max-profile-fields: 6

实测说明：默认 registration-open: false 意味着新装实例没有开放注册，第一个账号必须用 CLI 创建（admin account create，见安装指南 7.1）；开放注册的实例建议保留 reason-required: true 并调低 daily-limit 配合审核。密码强度策略在账号创建与改密两处生效（弱口令直接拒绝，实测见安装指南 FAQ Q2）。

5.6 媒体与存储参数

storage-backend: "local"              # local 或 s3
storage-local-base-path: "/gotosocial/storage"
storage-s3-endpoint: ""               # s3 模式的endpoint/bucket/密钥组
storage-s3-proxy: false
media-local-max-size: 40MiB           # 本地附件大小上限
media-image-size-hint: 5MiB           # 建议值（超提示不阻断）
media-video-size-hint: 40MiB
media-remote-max-size: 40MiB
media-thumb-max-pixels: 512           # 缩略图最长边
media-description-min-chars: 0        # 无障碍描述最少字数
media-description-max-chars: 5000
media-emoji-local-max-size: 50KiB
media-remote-cache-days: 30           # 远端媒体缓存保留天数（示例旧键）
media-remote-cache-duration: "7 days" # 现行键，实测 example 0.22.3 默认
media-cleanup-cron: "0 0 * * *"       # 每日清理
media-ffmpeg-pool-size: 1             # WASM ffmpeg 并发数

实测说明：标准构建内置 WASM 版 ffmpeg/ffprobe 做媒体处理，media-ffmpeg-pool-size 控制并发；上传 PNG 实测自动生成 original/01M64C6RR6PEZSFTTW3ESGYN4V.png 与 small/01M64C6RR6PEZSFTTW3ESGYN4V.jpeg 缩略图两级落盘（路径在 storage-local-base-path 下）。存储切换 S3 只需 storage-backend: "s3" + endpoint/bucket/密钥四键，媒体读走代理或直链由 storage-s3-proxy 控制。

💡 技术拓展：媒体对象存储选型——

后端语义适用
local 本地文件系统目录单机，默认
s3 S3 兼容对象存储（MinIO/OSS/R2 等）多副本、媒体量大、上 CDN

小型实例保持 local；媒体量到几十 GB 量级或需要多机共享存储时再切 S3 兼容后端。

后端	语义	适用
local	本地文件系统目录	单机，默认
s3	S3 兼容对象存储（MinIO/OSS/R2 等）	多副本、媒体量大、上 CDN

5.7 状态（发帖）参数

statuses-max-chars: 5000            # 单帖上限（比 Mastodon 默认 500 一致口径的 5 倍）
statuses-poll-max-options: 6
statuses-poll-option-max-chars: 50
statuses-media-max-files: 6
statuses-cleanup-cron: "0 1 * * 0"  # 每周清理远端过期帖
scheduled-statuses-max-total: 300   # 定时帖容量
scheduled-statuses-max-daily: 25

实测说明：发帖实测单帖带 hashtag 与媒体均按此上限工作；statuses-max-chars: 5000 对长文写作者友好，可按社区习惯调低。

5.8 TLS 参数

letsencrypt-enabled: false          # 内置 ACME 客户端开关
letsencrypt-port: 80                # ACME HTTP-01 端口
letsencrypt-cert-dir: "/gotosocial/storage/certs"
letsencrypt-email-address: ""
tls-certificate-chain: ""           # 手动证书（反代场景一般不用）
tls-certificate-key: ""

实测说明：本地 HTTP 模式全默认即可；对外 HTTPS 最省事是 letsencrypt-enabled: true + 域名 80 端口可达，证书落在 letsencrypt-cert-dir。若由 Nginx/Caddy 终止 TLS，GtS 保持 protocol: "https"、bind-address: 127.0.0.1，并在 trusted-proxies 里登记反代地址以获取真实客户端 IP。

5.9 邮件（SMTP）与 OIDC 参数

smtp-host: ""            # 五键全空=邮件功能关闭（默认）
smtp-port: 0
smtp-username/smtp-password: ""
smtp-from: ""
oidc-enabled: false      # OIDC 单点登录开关
oidc-issuer: ""          # 如 https://sso.example.org/realms/main
oidc-client-id/oidc-client-secret: ""
oidc-scopes: ["openid", "email", "profile"]
oidc-link-existing: false
oidc-admin-groups: []

实测说明：默认无 SMTP 时注册确认/密码重置走管理员手工链路（CLI confirm/password），这正是单管理员实例的默认工作模式；接了 SMTP 后开放注册的确认邮件才自动化。企业内网实例可把登录托管给 Keycloak 等 OIDC 提供方，oidc-admin-groups 可把 SSO 用户组映射为实例管理员。

5.10 高级与性能参数

advanced-rate-limit-requests: 300        # 5 分钟窗口限流（API+登录）
advanced-rate-limit-exceptions: []       # CIDR 豁免
advanced-throttling-multiplier: 8        # 每核并发节流系数
advanced-throttling-retry-after: 30s
advanced-sender-multiplier: 2            # 出站联邦投递批量系数
advanced-cookies-samesite: "lax"
cache-memory-target: (按宿主自动)         # 缓存总内存目标
cache-account-mem-ratio: 5               # 各类缓存占比（30+ 键）

实测说明：debug config 输出中 advanced-rate-limit-requests: 300、advanced-throttling-retry-after: 30000000000（纳秒=30s）与示例配置一致；缓存组按内存目标自动伸缩，小型实例无需手调，cache-memory-target 留默认即可，内存紧张时按比例整体下调。

六、生产配置模板

适用场景：2 核 4GB 内存 VPS、NVMe SSD、50 人以内朋友圈实例、域名 + Nginx 反代 HTTPS、SQLite 后端。基于实测环境推导，键值均有官方默认依据：

# /gotosocial/config.yaml —— 小型生产实例模板
log-level: "info"

# 身份：一次性定型，启用联邦后不可改
host: "social.example.org"
protocol: "https"
bind-address: "127.0.0.1"     # 仅监听回环，由 Nginx 对外
port: 8147
trusted-proxies:
  - "127.0.0.1"               # Nginx 反代地址，取真实客户端 IP

# 数据：SQLite 起步
db-type: "sqlite"
db-address: "/gotsocial/sqlite.db"

# 媒体：50 人规模收紧上传
storage-backend: "local"
storage-local-base-path: "/gotsocial/storage"
media-local-max-size: 20MiB
media-description-min-chars: 0

# 实例治理：朋友圈实例
accounts-registration-open: false       # 仅受邀注册
instance-federation-mode: "blocklist"

# TLS 由反代终止，内置 LE 关闭
letsencrypt-enabled: false

⚠️ 注意：模板中 db-address、storage-local-base-path 为示例路径，落到自己服务器时改为实际路径（如 /gotosocial/...）；host 换成自有域名。改完用 debug config 复核生效值再重启。

七、常见问题（FAQ）

Q1：改了 config.yaml 不生效？ A：三步排查——确认改的是 --config-path 指向的文件（systemd 单元里是 WorkingDirectory=/gotosocial 下的 config.yaml）；确认 systemctl restart gotosocial 已执行；用 debug config 核对生效值，若与文件不符说明被环境变量或 flag 覆盖（检查 systemd 单元 Environment= 与 ExecStart=）。

Q2：debug config 与 config.yaml 键名对不上？ A：debug config 输出 JSON 键与 yaml 键同名（连字符形式），直接 grep '"键名"'；输出为全量 249 键，含未在 yaml 中出现的内置默认。

Q3：SQLite 能否多进程并发访问？ A：可以。WAL 模式下读写并发、写串行，CLI 子命令（如 admin account create）与服务进程同时访问实测正常；db-sqlite-busy-timeout: "30m" 提供充足的写锁等待。但不要把 SQLite 数据库文件放 NFS 网络盘上（锁语义不可靠），单机本地盘即可。

Q4：host 写错已上线怎么办？ A：联邦身份（账号 @handle、actor URL）锚定 host，启用后有外部关注即不可安全更改；尚未联邦时改 host + 清空测试数据重建是最干净路径。确需保数据换域名属高级迁移，先在官方文档核实流程。

Q5：限流 300 次/5 分钟触发后表现？ A：超限请求按 advanced-throttling-retry-after（默认 30s）收到 Retry-After 响应；被自家监控探针高频打满时把探针网段加进 advanced-rate-limit-exceptions。

八、参考链接

官方配置总览：https://docs.gotosocial.org/en/latest/configuration/
官方示例配置（全参数注释）：包内 example/config.yaml（1661 行）
官方数据库配置：https://docs.gotosocial.org/en/latest/configuration/database/
官方存储配置：https://docs.gotosocial.org/en/latest/configuration/storage/
安装全流程实测见《Ubuntu 22.04 安装 GoToSocial 0.22.3 指南》；CLI 与 API 用法见《GoToSocial 0.22.3 常用 CLI 命令与 API 详解》；与 Mastodon 配置体系对照可参考《Mastodon 4.7.3 配置参数详解》。