Iceshrimp.NET v2026.1.3-beta Docker Compose 部署指南

目标：在一台 Linux 主机上，按官方知识库「Deploying to Docker」页给出的 Compose 编排，把 Iceshrimp.NET v2026.1.3-beta（2026-11-02 查询官方 release 页所得最新版）从零部署到「浏览器可登录、Mastodon API 可用」的状态。本文全部命令与回显均为 2026-11-02 实测记录。项目背景与选型对比见《Iceshrimp.NET v2026.1.3-beta 介绍与选型指南》。

一、环境信息

本章为实测环境口径，供读者复核。

组件与版本：Iceshrimp.NET v2026.1.3-beta（运行时自报版本串 Iceshrimp.NET v2026.1.3-beta+a998dc6e57, codename "phenidate"，.NET 运行时 10.0.14）。
官方发布产物：iceshrimp.dev/iceshrimp/iceshrimp.net:v2026.1.3-beta（Forgejo 内置制品库，匿名可获取，本地大小 270MB）；数据库为 postgres:18-alpine（官方模板指定，实测解析到 PostgreSQL 18.6）。
编排：Docker Compose v2 子命令形态（实测 Compose v5.6.1 / Engine 29.9.2）。
依赖形态（实测确证）：官方 compose 只有 web 与 db 两个服务，没有 Redis——Iceshrimp.NET 已把队列与缓存全部收敛进 PostgreSQL（官方 memory-management 页明示）。
域名口径：官方支持 WebDomain（实例域名）与 AccountDomain（账号域名）分离，本次实测用 ice.example.test / example.test；生产环境替换为真实域名即可。
宿主端口：本实测宿主分配 8129 作为 Web 入口（映射到服务内 3000）；自定义网段取 10.89.56.0/24 空闲槽位显式声明，生产单机部署可不写 ipam 段。

二、目录结构

官方部署文档第一步建目录并生成示例配置。实测目录结构如下：

iceshrimp-net/
├── docker-compose.yml
├── config/
│   └── configuration.ini        # 由 --printconfig 生成后按 Docker 口径修改
└── data/
    ├── db/                      # PostgreSQL 数据目录
    └── media/                   # 本地媒体目录（需 chown 1654:1654）

mkdir -p iceshrimp-net/config iceshrimp-net/data/media iceshrimp-net/data/db
cd iceshrimp-net

三、生成配置文件

官方文档给出的配置生成方式（实测可用，回显见下文）：用官方发布产物直接打印内置示例配置，重定向落盘：

docker run --rm iceshrimp.dev/iceshrimp/iceshrimp.net:v2026.1.3-beta --printconfig > config/configuration.ini

实测生成 349 行配置，节结构（grep -n '^\[' config/configuration.ini 实测回显节选）：

1:[Instance]
26:[Security]
91:[Network]
97:[Performance]
105:[Performance:QueueConcurrency]
113:[Backfill:Replies]
131:[Backfill:User]
146:[Queue:JobRetention]
150:[Database]
169:[Storage]
191:[Storage:Local]
195:[Storage:ObjectStorage]
209:[Storage:MediaProcessing]
309:[Storage:MediaProcessing:ImagePipeline:Original:Local]
312:[Storage:MediaProcessing:ImagePipeline:Original:Remote]
315:[Storage:MediaProcessing:ImagePipeline:Thumbnail:Local]
319:[Storage:MediaProcessing:ImagePipeline:Thumbnail:Remote]
324:[Storage:MediaProcessing:ImagePipeline:Public:Local]
331:[Storage:MediaProcessing:ImagePipeline:Public:Remote]
334:[Logging:LogLevel]
344:[OpenTelemetry]

按官方文档，Docker 部署必须改四处：

[Instance] 节：ListenHost 改为 0.0.0.0（默认 localhost，在编排内互访不可达）；WebDomain/AccountDomain 改为真实域名；
[Database] 节：Host 改为数据库服务名 db，Password 改为下一步生成的随机密码；
[Storage:Local] 节：Path 改为 /data/media；
其余节按需调整（逐项解说见《Iceshrimp.NET v2026.1.3-beta 配置参数详解》）。

3:ListenHost = 0.0.0.0
10:WebDomain = ice.example.test
11:AccountDomain = example.test
152:Host = db
156:Password = TLtJWfQIsbwCU7jU
193:Path = /data/media

数据库密码按官方建议随机生成：

head /dev/urandom | tr -dc A-Za-z0-9 | head -c16

四、docker-compose.yml

官方模板（deploying-to-docker 页，查询日期 2026-11-02）+ 本次实测的适配（固定版本标签、显式栈名、显式网段、宿主端口 8129）。实测文件全文：

name: iceshrimp-v2026.1.3-beta-stack

services:
  web:
    image: iceshrimp.dev/iceshrimp/iceshrimp.net:v2026.1.3-beta
    container_name: iceshrimp-v2026.1.3-beta-web
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "127.0.0.1:8129:3000"
    environment:
      - ICESHRIMP_CONFIG_OVERRIDES=/app/config/configuration.ini
    networks:
      - db
      - default
    volumes:
      - ./data/media:/data/media
      - ./config:/app/config:ro # This must be a directory for hot reload to work

  db:
    restart: unless-stopped
    image: postgres:18-alpine
    container_name: iceshrimp-v2026.1.3-beta-db
    shm_size: 256MB # Must be larger than the postgres shared_buffers setting (which defaults to 143MB)
    environment:
      - POSTGRES_DB=iceshrimp
      - POSTGRES_USER=iceshrimp
      - POSTGRES_PASSWORD=TLtJWfQIsbwCU7jU
    networks:
      - db
    volumes:
      - ./data/db:/var/lib/postgresql/18/docker

networks:
  db:
  default:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 10.89.56.0/24

要点说明：

配置以「覆盖文件」方式注入：官方把 ./config 只读挂到 /app/config，并用 ICESHRIMP_CONFIG_OVERRIDES 指向它。发布产物内置默认配置 + 挂载文件覆盖，该挂载点必须是目录（官方注释：hot reload 依赖目录形态）。
shm_size: 256MB 不能省：官方注释说明 PostgreSQL 默认 shared_buffers 约 143MB，共享内存必须大于它。
数据库数据目录：postgres:18-alpine 的 PGDATA 是 /var/lib/postgresql/18/docker（18 大版本号写死在路径里，跨大版本升级时注意改路径）。
官方模板 default 网络还带一段 IPv6 ULA（fd3a:25a5:9d9e::/48 随机前缀 + enable_ipv6: true），本次实测改用显式 IPv4 网段，两者按需取舍。
媒体目录授权（官方文档要求，runner 用户 UID/GID 为 1654）：

chown 1654:1654 data/media

五、启动与首次迁移

docker compose up -d

实测回显：

 Network iceshrimp-v202613-beta-stack_default Created 
 Container iceshrimp-v2026.1.3-beta-db Created 
 Container iceshrimp-v2026.1.3-beta-web Creating 
 Container iceshrimp-v2026.1.3-beta-web Created 
 Container iceshrimp-v2026.1.3-beta-db Starting 
 Container iceshrimp-v2026.1.3-beta-db Started 
 Container iceshrimp-v2026.1.3-beta-web Starting 
 Container iceshrimp-v2026.1.3-beta-web Started

（注：栈名中的 . 被 Compose 归一化剔除，网络名显示为 iceshrimp-v202613-beta-stack_*，属正常现象。）

首次启动会自动执行全部数据库迁移，实测日志（docker compose logs web 节选，逐行照抄）：

iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Iceshrimp.NET v2026.1.3-beta+a998dc6e57, codename "phenidate" (example.test)
iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Validating configuration...
iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Verifying database connection...
iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Running migrations...
iceshrimp-v2026.1.3-beta-web  | info: [core] Microsoft.EntityFrameworkCore.Migrations > Applying migration '20240107171910_Initial'.
iceshrimp-v2026.1.3-beta-web  | info: [core] Microsoft.EntityFrameworkCore.Migrations > Applying migration '20240107181428_RenameProperties'.

迁移中段会出现数条交互式提示（全新库上耗时以秒计，大库才需担心）：

iceshrimp-v2026.1.3-beta-web  | Fixing up note visibility enums, please hang tight!
iceshrimp-v2026.1.3-beta-web  | This may take a long time (15-30 minutes), especially if your database is unusually large or you're running low end hardware.

就绪标志（实测）：

iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Using [LibVips, ImageSharp] for image processing.
iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Found 0 plugins in /app/plugins/v1.
iceshrimp-v2026.1.3-beta-web  | info: [core] Iceshrimp.Backend > Startup complete after 3253 ms.
iceshrimp-v2026.1.3-beta-web  | info: [core] Microsoft.Hosting.Lifetime > Now listening on: http://0.0.0.0:3000
iceshrimp-v2026.1.3-beta-web  | info: [core] Microsoft.Hosting.Lifetime > Application started. Press Ctrl+C to shut down.
iceshrimp-v2026.1.3-beta-web  | info: [core] Microsoft.Hosting.Lifetime > Hosting environment: Production

docker compose ps 实测回显：

NAME                           IMAGE                                                  COMMAND                  SERVICE   CREATED          STATUS          PORTS
iceshrimp-v2026.1.3-beta-db    postgres:18-alpine                                     "docker-entrypoint.s…"   db        26 seconds ago   Up 25 seconds   5432/tcp
iceshrimp-v2026.1.3-beta-web   iceshrimp.dev/iceshrimp/iceshrimp.net:v2026.1.3-beta   "./Iceshrimp.Backend…"   web       26 seconds ago   Up 25 seconds   127.0.0.1:8129->3000/tcp

六、服务可用性验证

Iceshrimp.NET 严格校验请求的 Host 头（须匹配 WebDomain/AccountDomain），本机 curl 验证需显式带 Host：

curl -s -H "Host: ice.example.test" http://127.0.0.1:8129/api/v1/instance

实测返回（节选）：

{
    "stats": {
        "user_count": 0,
        "status_count": 0,
        "domain_count": 0
    },
    "version": "4.2.1 (compatible; Iceshrimp.NET/2026.1.3-beta)",
    "max_toot_chars": 8192,
    "uri": "example.test",
    "title": "example.test",
    "registrations": false,
    "invites_enabled": false,
    "approval_required": true
}

/api/v1/instance 直接以 Mastodon 4.2.1 兼容口径应答，证明 Mastodon 客户端可直连。其余验证点实测：

curl -s -H "Host: ice.example.test" http://127.0.0.1:8129/.well-known/nodeinfo
{"links":[{"rel":"http://nodeinfo.diaspora.software/ns/schema/2.1","href":"https://ice.example.test/nodeinfo/2.1"},{"rel":"http://nodeinfo.diaspora.software/ns/schema/2.0","href":"https://ice.example.test/nodeinfo/2.0"}]}

curl -s -H "Host: ice.example.test" http://127.0.0.1:8129/nodeinfo/2.1 | head -c 200
{"version":"2.1","software":{"name":"Iceshrimp.NET","version":"2026.1.3-beta+a998dc6e57","codename":"phenidate",...

curl -s -H "Host: example.test" "http://127.0.0.1:8129/.well-known/webfinger?resource=acct:root@example.test"
{"links":[{"rel":"self","type":"application/activity+json","href":"https://ice.example.test/users/at2flvxvfcmfvnsm"},...

WebFinger 用 AccountDomain（example.test）查询、返回 WebDomain（ice.example.test）上的 actor，分域模型工作正常；
前端页 curl -H "Host: ice.example.test" http://127.0.0.1:8129/ 返回 200，<title>Home - Iceshrimp.NET</title>（Blazor WASM 界面）；
管理面板 /admin 与队列面板 /queue 未登录时返回 302（跳登录），登录后浏览器访问即可。

七、创建管理员

官方 post-install 指引：用后端进程带 --create-admin-user <用户名> 参数创建首个管理员。官方文档给出的运行方式（实测可用）：

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --create-admin-user root

实测回显：

info: [core] Iceshrimp.Backend > Iceshrimp.NET v2026.1.3-beta+a998dc6e57, codename "phenidate" (example.test)
info: [core] Iceshrimp.Backend > Validating configuration...
info: [core] Iceshrimp.Backend > Verifying database connection...
info: [core] Iceshrimp.Backend > Creating user root...
info: [core] Iceshrimp.Backend > Successfully created admin user.
info: [core] Iceshrimp.Backend > Username: root
info: [core] Iceshrimp.Backend > Password: GdqlVrwypjUbooNy

注意：密码是随机生成并打印的，不接受交互式输入（--reset-password 同样只生成随机新密码，实测见 11.4 节）。要把密码改成本文示例账号的 q1w2e3r4，走 Web API 两步（实测可用；q1w2e3r4 恰好满足官方「至少 8 字符」下限）：

TOK=$(curl -s -H "Host: ice.example.test" -H "Content-Type: application/json" \
  -d '{"username":"root","password":"GdqlVrwypjUbooNy"}' \
  http://127.0.0.1:8129/api/iceshrimp/auth/login | python3 -c "import json,sys;print(json.load(sys.stdin)['token'])")

curl -s -H "Host: ice.example.test" -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  -d '{"oldPassword":"GdqlVrwypjUbooNy","newPassword":"q1w2e3r4"}' \
  http://127.0.0.1:8129/api/iceshrimp/auth/change-password

实测返回 {"status":"authenticated","isAdmin":true,"isModerator":false,"token":"...","user":{"id":"at2flvxvfcmfvnsm","username":"root",...}}，随后用 root / q1w2e3r4 登录 / 即可进入自带前端与 /admin 管理面板。

八、反向代理

生产部署需在 80/443 与 Web 服务间加反代（官方 post-install 页给出三套模板，查询日期 2026-11-02）。以 Nginx 为例（web.instance.tld 换成 WebDomain，端口换成宿主映射端口）：

map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;
}

server {
  # Insert or `include` your SSL configuration here
  server_name web.instance.tld;
  location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }
}

Caddy 只需 web.instance.tld { reverse_proxy :3000 } 两行。Upgrade/Connection 头必须保留——前端实时时间线走 SignalR/WebSocket。若采用 WebDomain ≠ AccountDomain 的分域部署，完成后还要按官方 split-domain-setup 页补账号域名的发现记录，否则联邦不可达。

九、升级与回滚

官方 release 页长期强调「强烈建议所有服务端管理员升级」（v2026.1.x 线全部是安全热修复）。升级三步：

备份：pg_dump 数据库 + 打包 data/media（官方 database-maintenance 页同样要求先备份再动手）；
把 compose 中版本标签改为新 release（如 v2026.1.4-beta），docker compose up -d——compose 自动获取新版发布产物，服务重启时自动执行增量迁移；
回滚：标签改回旧版本重新 up -d。若新版本已执行过迁移，回滚旧版本不保证兼容，务必以第 1 步备份兜底。

配置改动本身几乎全部即时生效（热重载），无需重启服务，详见《Iceshrimp.NET v2026.1.3-beta 配置参数详解》。

十、资源占用实测

官方发布产物本地大小 270MB；postgres:18-alpine 433MB；
空载驻留内存（docker stats --no-stream 实测）：web 服务 455MiB、db 服务 97.61MiB，合计约 550MiB，与官方「最低 1GB、推荐 2GB」口径吻合（.NET 运行时按可用内存伸缩缓存，给多少用多少，无 JVM 式堆上限问题）；
全新安装迁移完成后数据库实测：PostgreSQL 18.6，库大小 13 MB，public 模式 83 张表；
首次迁移 + 启动总耗时实测 < 1 分钟（Startup complete after 3253 ms 为迁移完成后的应用启动段）。

十一、排障实录

11.1 本机 curl 返回 421

现象（实测）：不带 Host 头直接 curl http://127.0.0.1:8129/：

http_code=421
{"error":"This server is not configured to respond to this request."}

原因：Iceshrimp.NET 校验 Host 头必须属于 WebDomain/AccountDomain（或 [Instance] 节 AdditionalDomains 白名单）。用 IP/错误域名访问一律 421。解决：带正确 Host 头测试，或把额外域名加入 AdditionalDomains。

11.2 首次启动日志成串 `fail: Failed executing DbCommand`

现象（实测）：全新部署第一次 logs web 出现多条：

fail: [core] Microsoft.EntityFrameworkCore.Database.Command:
      Failed executing DbCommand (7ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      SELECT "MigrationId", "ProductVersion"
      FROM "__EFMigrationsHistory"
      ORDER BY "MigrationId";

判定：无害。这是 EF Core 在空库上探测迁移历史表（表尚不存在）的正常流程，随后即出现 Running migrations... 并逐条 Applying。只有伴随 Failed to connect to database 才需要处理。

11.3 数据库密码错误导致启动失败

现象（实测，把 [Database] 的 Password 改错后运行维护命令）：

info: [core] Iceshrimp.Backend > Verifying database connection...
fail: [core] Microsoft.EntityFrameworkCore.Database.Connection > An error occurred using the connection to database 'iceshrimp' on server 'tcp://db:5432'.
crit: [core] Iceshrimp.Backend > Failed to connect to database. Please make sure your configuration is correct.
fail: [core] Iceshrimp.Backend:
      Additional information: Npgsql.PostgresException (0x80004005): 28P01: password authentication failed for user "iceshrimp"

解决：configuration.ini 的 [Database] 密码必须与 compose 中 POSTGRES_PASSWORD 完全一致；改过 POSTGRES_PASSWORD 后旧数据卷不会自动同步密码，需进数据库改角色密码或清卷重来。

11.4 `--reset-password` 不接受人工输入

现象（实测）：向命令 stdin 喂入新密码无效，回显仍是随机密码：

printf 'q1w2e3r4\nq1w2e3r4\n' | docker compose run --rm -T --entrypoint ./Iceshrimp.Backend web --reset-password root
...
info: [core] Iceshrimp.Backend > Password for user root was reset to: EmcqfS3r3unEAX0d

结论：CLI 的创建/重置密码一律随机生成并打印，人工设定密码须走登录后的 change-password 接口或自带前端设置页（见第七节）。

11.5 Mastodon OAuth 密码模式不可用

现象（实测）：/api/v1/apps 注册应用成功（返回 client_id/client_secret/vapid_key），但 POST /oauth/token 的 grant_type=password 一律返回：

{"error":"BadRequest","error_description":"One or more validation errors occurred."}

带域名用户名（root@example.test）同样 400。结论：v2026.1.3-beta 不开放密码模式，第三方客户端须走标准授权码流程（浏览器授权）或实例 Web 登录接口。

十二、日常运维命令入口

官方文档口径：所有后端维护命令都通过同一条入口执行——

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --help

全部子命令逐项实测与用法见《Iceshrimp.NET v2026.1.3-beta 常用 CLI 命令与工具详解》。

十三、延伸阅读

选型与版本策略：《Iceshrimp.NET v2026.1.3-beta 介绍与选型指南》
官方部署文档：https://kb.iceshrimp.dev/s/docs/doc/deploying-to-docker-yZTXsWENAa （查询日期 2026-11-02）
官方 post-install 指引：https://kb.iceshrimp.dev/s/docs/doc/post-install-guide-caco15miOE （查询日期 2026-11-02）

Iceshrimp.NET v2026.1.3-beta Docker Compose 部署指南

Iceshrimp.NET v2026.1.3-beta Docker Compose 部署指南

一、环境信息

二、目录结构

三、生成配置文件

四、docker-compose.yml

五、启动与首次迁移

六、服务可用性验证

七、创建管理员

八、反向代理

九、升级与回滚

十、资源占用实测

十一、排障实录

11.1 本机 curl 返回 421

11.2 首次启动日志成串 fail: Failed executing DbCommand

11.3 数据库密码错误导致启动失败

11.4 --reset-password 不接受人工输入

11.5 Mastodon OAuth 密码模式不可用

十二、日常运维命令入口

十三、延伸阅读

11.2 首次启动日志成串 `fail: Failed executing DbCommand`

11.4 `--reset-password` 不接受人工输入