Iceshrimp.NET v2026.1.3-beta 配置参数详解

以 v2026.1.3-beta --printconfig 实测导出的 349 行配置为底本，逐节讲解 Instance/Security/Network/Performance/Backfill/Database/Storage/MediaProcessing/Logging/OpenTelemetry 全部参数与默认值，含热重载实测、GC 内存调优与 dev/release 配置差异

Iceshrimp.NET联邦平台ActivityPub.NET2026/11/02

Iceshrimp.NET v2026.1.3-beta 配置参数详解

本文以 v2026.1.3-beta 发布产物 --printconfig 实测导出的 349 行示例配置为底本（导出方法见 《Iceshrimp.NET v2026.1.3-beta Docker Compose 部署指南》 第三节），逐节讲解全部参数、默认值与生效方式，并附热重载实测记录。项目背景见 《Iceshrimp.NET v2026.1.3-beta 介绍与选型指南》。

一、配置体系与加载机制

1.1 文件格式与查找顺序

Iceshrimp.NET 的配置是单个 .ini 文件（官方特性矩阵自评「.ini 格式 + 热重载」为 ⭐⭐⭐）。启动时按以下顺序查找：

  1. 工作目录下的 configuration.ini；
  2. 环境变量 ICESHRIMP_CONFIG 指定的路径（主配置）；
  3. 环境变量 ICESHRIMP_CONFIG_OVERRIDES 指定的路径（覆盖配置）。

官方知识库 post-install 页（查询日期 2026-11-02）明确支持「双文件布局」：主配置 + configuration.overrides.ini 分离管理，便于把易变参数（密码、域名）与稳定参数分开放。Docker 部署正是用覆盖文件方式注入（挂载 ./config 目录 → ICESHRIMP_CONFIG_OVERRIDES=/app/config/configuration.ini）。

1.2 热重载

官方口径：除 [Instance] 与 [Database] 两节外，其余各节的修改几乎全部即时生效，无需重启（这两节只在初始化时被读取）。配置目录必须以「目录」形态挂载，否则热重载失效（官方 compose 注释原文：This must be a directory for hot reload to work）。

实测记录见第十二节。

1.3 环境变量

与日志相关的三个环境变量（官方 post-install 页）：

  • NO_COLOR=1：禁用彩色日志（即使终端支持或检测到 systemd）；
  • FORCE_COLOR=1：强制彩色日志；
  • LOG_TIMESTAMPS=1：日志行加时间戳前缀。

内存/GC 调优类环境变量见第十三节。

二、[Instance]：监听与域名

参数默认值说明
ListenPort3000HTTP 监听端口
ListenHostlocalhost监听地址；Docker 部署必须改 0.0.0.0，裸机反代场景保持 localhost
ListenSocket / ListenSocketPerms注释掉改走 Unix socket（如 /var/run/iceshrimp/iceshrimp.net.sock），权限默认 660，注意文件系统授权
WebDomainshrimp.example.org实例域名（服务与 actor 所在域）。官方警告：初始设置后修改会破坏联邦
AccountDomainexample.org账号域名（用户 @user@domain 里的域）。同样不可事后修改
AdditionalDomains空额外允许 API 访问的域名（逗号分隔）。Akkoma-FE 等前端经反代从前端域发请求时需要加入，否则生产环境默认被拒
CharacterLimit8192本地发帖字符上限（全局上限 100000）。实测热重载生效（见十二节）
RedirectIndexTo注释掉未登录访问首页时重定向到指定 URL（相对如 /@username，或绝对 URL），单用户实例常用

WebDomain 与 AccountDomain 可以相同（同域部署），也可以不同（分域部署，需按官方 split-domain-setup 页补发现记录）。实测两域分离时，WebFinger 以 AccountDomain 应答、actor 指向 WebDomain，行为正确。

三、[Security]：安全与联邦策略

参数默认值说明
AuthorizedFetchtrue要求入站 ActivityPub 请求带合法 HTTP/LD 签名。官方强烈建议保留开启，尤其使用 block/allow 联邦模式时
ValidateRequestSignaturestrue校验入站 AP 请求（AuthorizedFetch=true 时恒开）。关闭可提升大流量时性能，但远端无法取回仅关注者可见的帖子
AttachLdSignaturesfalse出站活动附 LD 签名（转发的活动无论此项如何都会签名）
AcceptLdSignaturesfalse接受 LD 签名活动；需要接收转发活动时开启
AllowLoopbackfalse允许访问回环地址（SSRF 防护开关）
AllowLocalIPv4false允许访问 RFC1918/链路本地 IPv4
AllowLocalIPv6false允许访问 ULA/链路本地 IPv6
ExceptionVerbosityBasicAPI 错误详细度：None（仅请求 ID+状态码）/Basic（错误码+消息）/Full（错误详情+异常类名）/Verbose（堆栈，仅 HTML）。注意：dev 分支此项第四档叫 Debug，release 为 Verbose
RegistrationsClosed注册模式：Closed/Invite/Open。官方 post-install 特别提醒：除非确定要开放注册，保持限制模式
FederationModeBlockList联邦名单模式：BlockList（默认拉黑制）或 AllowList（白名单制）
ExposeFederationListRegistered黑/白名单可见性：Public/Registered/Hide
ExposeBlockReasonsRegistered封禁原因可见性（同上三档）。官方注释提醒：公开封禁原因可能涉诽谤与骚扰风险，慎重选 Public
PublicPreviewPublic本地公开帖预览：Public（无限制）/Restricted（隐藏远端回复）/RestrictedNoMedia（再隐藏媒体）/Lockdown（关闭公开预览与除认证外全部匿名 API）

四、[Network]：出站代理

参数默认说明
HttpProxy注释掉全部出站请求走指定代理（127.0.0.1:8080 形态）。修改后需重启后端才生效（官方注释明示）
HttpProxyUser / HttpProxyPass注释掉代理认证

五、[Performance]：并发与队列

参数默认值说明
FederationRequestHandlerConcurrency0并发处理的入站联邦请求数（0=不限）。超限后入站请求先在内存缓冲。低配机器可设小值，因为验签是 CPU 密集操作

[Performance:QueueConcurrency] 子节——每个队列的并发作业数（默认值实测）：

Inbox = 4
Deliver = 20
PreDeliver = 4
BackgroundTask = 4
Backfill = 10
BackfillUser = 10

[Queue:JobRetention] 子节——队列历史保留：

Completed = 10
Failed = 100

每 15 分钟按「最旧优先」裁剪超额作业（-1 = 不限制）。队列面板 /queue 可实时观察（管理员登录访问）。

六、[Backfill:*]：内容回填（实验特性）

6.1 [Backfill:Replies] 回复回填

参数默认说明
Enabledfalse拉取远端帖子的回复树。官方警告：性能影响大、实验特性，仅愿意接受不稳定时开启；且只对暴露 replies collection 的远端实例有效
FetchAsUserfalse以请求者身份而非实例匿名 actor 拉取：能看到该用户可见的私享回复，但远端可借此做「已读回执」追踪；单用户实例可考虑开启
NewNoteDelay5m新帖延迟回填窗口，让回复先积累
RefreshAfter15m同一帖子两次回填的最小间隔

6.2 [Backfill:User] 用户时间线回填

参数默认说明
Enabledfalse关注时回填该用户历史发帖（同样实验特性，依赖远端 outbox collection）
MaxItems100回填活动条数上限（不含其回复线程）
RefreshAfter30d回填冷却

七、[Database]：数据库

参数默认说明
Hostlocalhost主机/IP 或 Unix socket 目录路径（走 socket 也必须写端口）
Port5432端口
Database / Username / Passwordiceshrimp库名/用户/密码，须与数据库侧一致（错配报错见部署篇 11.3）
MaxConnections100连接池上限（有效范围 1-1000）
Multiplexingtrue连接复用。官方强烈建议保持开启，否则很容易耗尽连接池
ParameterLoggingfalse出错时记录 SQL 参数。可能含敏感信息，仅调试开启

本节不支持热重载。另外因 Redis 已被移除、队列与缓存全走 PostgreSQL，官方 memory-management 页强调「跑一遍 PGTune 比以往任何时候都重要」——数据库调优直接决定整体表现。

八、[Storage]：媒体存储

8.1 主节

参数默认说明
ProviderLocalLocal 或 ObjectStorage
MaxUploadSize100M本地上传大小上限（-1 不限）
MaxCacheSize20M远端媒体缓存上限，超过永不缓存（-1 不限）
MediaRetention30d远端媒体缓存保留时长（0=关闭，-1=永久）
CleanAvatars / CleanBannersfalse是否连头像/封面一起按保留期清理
ProxyRemoteMediatrue代理远端媒体（保护用户 IP，代价是带宽）。住宅线路托管的实例建议关闭

8.2 [Storage:Local]

Path——媒体落盘路径，服务用户必须可写（Docker 部署即 /data/media，宿主侧目录需 chown 1654:1654）。

8.3 [Storage:ObjectStorage]

S3 兼容对象存储接入（默认整节注释）：Endpoint、Region、KeyId、SecretKey、Bucket、Prefix、AccessUrl（对外访问前缀）、SetAcl（如 public-read）、DisableValidation（前置 CDN/缓存导致重启校验失败时才关）。本地存量迁往对象存储用 CLI --migrate-storage（见 《Iceshrimp.NET v2026.1.3-beta 常用 CLI 命令与工具详解》）。

九、[Storage:MediaProcessing]：图片处理管线

参数默认说明
ImageProcessorImageSharpImageSharp（.NET 库，慢但内存低、无外部依赖）/LibVips（原生库，快但内存占用高且尖峰，需内置或系统安装）/None（关闭处理，最快最省——注意：本地图片元数据（如 GPS）将不会被剥离）。实测发布产物日志为 Using [LibVips, ImageSharp] for image processing.（LibVips 优先、ImageSharp 兜底）
LocalOnlyfalse只处理本地媒体（CPU 受限环境：保留远端缓存但不做远端转码）
MaxFileSize10M超过此大小的文件不进入处理管线（本地图片元数据不剥离！）
MaxResolutionMpx30处理分辨率上限（百万像素）。官方注释：极端场景每百万像素需约 4MB 内存
FailIfImageExceedsMaxResfalse超限本地图片直接拒绝而非跳过（不想泄露 GPS 就开）
ImageProcessorConcurrency8并发编码任务数（0 不限）
VipsAllowUntrustedJxl/J2k/SvgfalseLibVips 默认禁用未模糊测试格式（v2026.1.2-beta 起的安全默认），按需逐项放开，有 DoS/RCE 风险

9.1 [Storage:MediaProcessing:ImagePipeline:*] 六节管线

节名模式 ImagePipeline:<版本>:<来源>，版本 × 来源共六节（默认值实测）：

  • Original（原图，Public 不存在时使用）：Local/Remote 均 Format = Keep（不转码，仅做 blurhash/去重等）；
  • Thumbnail（时间线缩略图）：Format = Webp、TargetRes = 1000，Remote 版另设 QualityFactorPngSource = 75；
  • Public（替代 Original 对外分发，本地件用于剥离元数据的小尺寸版）：Local 为 Webp/TargetRes = 2048（官方注释：本地公开图会联邦，远端软件不认格式可能摄取失败），Remote 为 None（不生成）。

可选编码参数：Format（None/Keep/Webp/Avif/Jxl，后两者仅 LibVips）、QualityFactor（1-100，默认 75）、QualityFactorPngSource（默认 100）、TargetRes（最长边像素，源图更小则不放大）、WebpCompressionMode/AvifCompressionMode（Lossy/NearLossless/Lossless）、AvifBitDepth（8-12）、JxlCompressionMode、JxlEffort（1-9，默认 7）。

十、[Logging:LogLevel]：日志级别

实测默认值：

Default = Information
Iceshrimp = Information
Microsoft.AspNetCore = Warning
Microsoft.EntityFrameworkCore = Warning
Microsoft.EntityFrameworkCore.Update = Critical
Microsoft.EntityFrameworkCore.Migrations = Information
Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager = Critical
Iceshrimp.Backend.SignalR.Authentication.HubAuthenticationHandler = Warning

官方 post-install 说明：级别递归生效（子命名空间继承），更具体的条目覆盖更宽泛的条目——想调试某组件不必全局开 Debug 刷屏。

十一、[OpenTelemetry]

Enabled = false。开启后 traces/metrics/logs 走 OTel 导出，配合官方 v2026.1-beta 引入的管理员指标能力（配置细节见官方注释链接的 opentelemetry-dotnet-instrumentation 文档，查询日期 2026-11-02）。

十二、热重载实测记录

2026-11-02 在部署篇环境上实测热重载，步骤与回显：

  1. 编辑挂载的覆盖文件 config/configuration.ini：CharacterLimit = 8192 → 9000，不重启任何服务，等待 8 秒；
  2. 验证生效：
curl -s -H "Host: ice.example.test" http://127.0.0.1:8129/api/v1/instance | python3 -c "import json,sys;print('max_toot_chars =',json.load(sys.stdin)['max_toot_chars'])"
max_toot_chars = 9000
  1. 期间 docker compose logs web --since 30s 无重启、无报错——服务进程未动，配置已生效。

运维口径：官方 post-install 页的原则是「几乎所有节的修改即时生效，例外是 [Instance] 与 [Database] 两节（初始化后不再影响程序逻辑）」——这主要针对监听地址、域名、数据库连接这类进程级参数（ListenHost、WebDomain/AccountDomain、Host/Password 等，改了必须重启，HttpProxy 官方注释亦明示需重启）。而 CharacterLimit 这类被 API 应答动态读取的实例参数，实测运行期即生效。稳妥做法：改配置前对照官方注释，凡标注「restart required」或属于监听/连接/域名语义的参数，改完重启后端进程（compose 场景 docker compose restart web）。

十三、内存与 GC 调优（环境变量层）

官方 memory-management 页（查询日期 2026-11-02）口径整理。.NET 运行时与 JVM 不同，没有「堆上限必须显式设置」的要求：GC 采用 DATAS「混合」模式（按需分配额外堆），默认配置即适合绝大多数场景，官方原话「升级后你大概率不需要调整任何 GC 选项」。低配环境的官方 tl;dr：

DOTNET_gcServer=0            # 切 Workstation GC，省内存换 GC 性能
MALLOC_TRIM_THRESHOLD_=131072  # glibc 内存归还阈值（musl 系统跳过）

其余可调项（均为环境变量，十六进制数值）：

变量作用
DOTNET_GCHeapCountGC 堆/工作线程数（默认每 CPU 一线程）
DOTNET_GCNoAffinitize=1取消 GC 线程 CPU 亲和性绑定
DOTNET_GCHeapHardLimit / DOTNET_GCHeapHardLimitPercent显式限制 GC 堆（字节/占系统内存百分比，64=100%）
DOTNET_GCHighMemPercent进入更激进 GC 模式的内存压力阈值（默认 5A=90%）
DOTNET_GCConserveMemory0-9 内存节约倾向，建议起点 5-7
DOTNET_gcConcurrent=0关闭并发 GC（官方不推荐）

给进程限额优先用 cgroup（systemd MemoryMax=1G，或 compose deploy.resources.limits.memory），比调 GC 参数更可预期。图片处理是内存大头：受限环境换 ImageProcessor = ImageSharp 或 None、压小 MaxResolutionMpx。

十四、dev 与 release 配置差异（版本注记）

实测对比 dev 分支 359 行与 v2026.1.3-beta 导出 349 行：

  • dev 新增 [Translation] 节（DefaultTranslationLanguage，需翻译插件支撑）；
  • dev 新增 VipsGammaCorrectLinearScaling（缩放前线性色彩空间转换）；
  • dev 将 ExceptionVerbosity 第四档 Verbose 更名 Debug。

以发布产物 --printconfig 输出为准编写配置最稳妥；升级后建议重新导出一份新示例对照迁移。

十五、延伸阅读

Iceshrimp.NET v2026.1.3-beta 配置参数详解 - Quzuo