diaspora* Docker Compose 部署指南

本文是 diaspora* 专栏的部署篇，基于 0.9.1.0 在 Ubuntu 24.04.5 / Docker 29.9.2 / Docker Compose v5.6.1 环境完整实测。组件定位与选型判断请先读《diaspora* 介绍与选型指南》；文中所有命令回显均为逐字实录，pod 域名以 pod.example.com 占位。

一、环境信息

1.1 目标版本与来源

组件：diaspora* v0.9.1.0（官方最新稳定版，2026-04-07 发布于 GitHub Releases）；
源码包：https://github.com/diaspora/diaspora/archive/refs/tags/v0.9.1.0.tar.gz（10,376,664 B）；
技术栈：Rails 6.1.7.10 + Puma 7.2.0 + Sidekiq 7.3.10，Ruby 3.3，PostgreSQL + Redis。

1.2 实测宿主机环境

Ubuntu 24.04.5 LTS / x86_64
Docker 29.9.2 / Docker Compose v5.6.1
宿主空闲端口：8143-8146（8147/8148 被并发服务占用，实测避让）
docker 子网 10.89.68.0/24 空闲

1.3 部署拓扑

一个生产 pod 需要 4 个容器（官方 Procfile 即 web + sidekiq 两进程，加数据库与队列后端）：

服务	镜像	角色	端口/说明
web	自建 `diaspora-app:0.9.1.0`	puma 承载 Rails 应用与联邦端点	宿主 `8143:443`（puma 原生 `ssl://`，无需 nginx）
sidekiq	同镜像	联邦推送、定时作业（7 个 cron 作业）	不对外
db	`postgres:15`	主数据库	内部 5432
redis	`redis:7`	Sidekiq 队列/缓存	内部 6379

二、镜像选型说明

2.1 为什么不能用官方镜像

官方安装文档源仓库（diaspora/north-star，contents/install/new_pod/docker.md）明确：diasporasocial/diaspora-dev 镜像与 ./script/diaspora-dev 仅用于开发环境，不可生产。官方 Docker Hub 没有生产形态镜像，这是本指南自建镜像的根本原因。

2.2 自建镜像的基线选择

基础镜像 ruby:3.3-slim-trixie：对齐 Changelog 0.9.0.0 的官方建议（We recommend setting up new pods using Ruby 3.3）；
apt 依赖清单对齐官方开发 Dockerfile 的系统依赖（imagemagick、libmagickwand-dev、libpq-dev 等），并补 libidn-dev（见第十一节排障 1）；
前端依赖按 0.9.0.0 起的要求用 yarn 安装（yarn@1.22.22）。

三、前置条件

3.1 资源与域名

内存：空载单 pod 四个容器合计约 470 MiB（实测 web 212.5 / sidekiq 198.7 / db 53.3 / redis 7.0 MiB），建议预留 ≥1 GB；
磁盘：镜像 2.16 GB + 数据目录；
域名与 TLS 证书：联邦发现（WebFinger）永远优先 https://，http 回退仅在 development 环境启用（源码 config/initializers/diaspora_federation.rb：webfinger_http_fallback = Rails.env == "development"）。生产 pod 必须 HTTPS，纯 http 的 pod 之间无法联邦。测试环境用自签 CA：

mkdir -p data/certs && cd data/certs
openssl req -x509 -newkey rsa:2048 -sha256 -days 3650 -nodes \
  -keyout ca.key -out ca.crt -subj "/CN=S8 Diaspora Test CA"
h=pod.example.com
openssl req -newkey rsa:2048 -nodes -keyout $h.key -out $h.csr -subj "/CN=$h"
printf "subjectAltName=DNS:%s\n" $h > san.ext
openssl x509 -req -in $h.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 825 -sha256 -extfile san.ext -out $h.crt
# 联邦出站信任库 = 测试CA + 系统CA
cat ca.crt /etc/ssl/certs/ca-certificates.crt > ca-combined.pem

生产环境请把自签换成 Let's Encrypt 等受信证书，ca-combined.pem 直接用系统 CA 包即可。

3.2 构建上下文准备

tmp/diaspora/                 # 构建上下文
├── diaspora-0.9.1.0/         # 源码解压目录
├── diaspora-v0.9.1.0.tar.gz  # 源码发布 tar（AGPL 要求 /source 页提供源码包）
├── build/                    # Dockerfile、diaspora.toml、database.yml、entrypoint.sh
└── docker-compose.yml

四、部署步骤

4.1 Dockerfile（build/Dockerfile）

# diaspora* 0.9.1.0 生产镜像（非官方 docker/develop 开发镜像）
# 构建上下文 = tmp/diaspora/（含源码目录 diaspora-0.9.1.0 与发布 tar 包）
FROM docker.io/library/ruby:3.3-slim-trixie

ENV DEBIAN_FRONTEND=noninteractive \
    OPENSSL_CONF=/etc/ssl/ \
    RAILS_ENV=production \
    GEM_HOME=/diaspora/vendor/bundle \
    BUNDLE_APP_CONFIG=/diaspora/.bundle

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      build-essential \
      cmake \
      curl \
      git \
      imagemagick \
      libcurl4-openssl-dev \
      libffi-dev \
      libidn-dev \
      libjemalloc2 \
      libmagickwand-dev \
      libpq-dev \
      libssl-dev \
      libxml2-dev \
      libxslt1-dev \
      libyaml-dev \
      nodejs \
      npm \
      pkg-config \
      tzdata \
 && npm install -g yarn@1.22.22 \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /diaspora
COPY diaspora-0.9.1.0/ /diaspora/
# AGPL 源码包：/source 页与 script/server 检查需要 public/source.tar.gz
COPY diaspora-v0.9.1.0.tar.gz /diaspora/public/source.tar.gz
COPY build/diaspora.toml /diaspora/config/diaspora.toml
COPY build/database.yml /diaspora/config/database.yml
COPY build/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh \
 && mkdir -p /diaspora/public/uploads /diaspora/log /diaspora/tmp/pids

# 等价于官方 script/configure_bundler（production 形态）
RUN bundle config set --local jobs "$(nproc)" \
 && bundle config set --local with postgresql \
 && bundle config set --local without "development test mysql" \
 && bundle config set --local path vendor/bundle \
 && bundle config set --local frozen true \
 && bundle config set --local disable_shared_gems true \
 && bundle install --full-index

RUN yarn install --frozen-lockfile

# 会话密钥（生产应持久化 config/initializers/secret_token.rb，本测试镜像内烘焙）
RUN bin/rake generate:secret_token

# 静态资源预编译（耗时大头）
RUN bin/rake assets:precompile

EXPOSE 80
ENTRYPOINT ["/entrypoint.sh"]
CMD ["bin/puma", "-C", "config/puma.rb"]

要点：

bundle config set --local with postgresql：Gemfile 的数据库 gem 在可选组里（group :postgresql, optional: true），必须显式启用，否则启动时报缺 pg；
public/source.tar.gz：AGPL 源码分发义务，script/server 与 /source 页会检查；
会话密钥由 bin/rake generate:secret_token 生成（实测确认没有 make_admin 之类的 rake 任务，管理员提权走 rails runner，见 4.6）；生产持久化方案见 5.2。

4.2 镜像内烘焙配置（build/diaspora.toml）

## 镜像内烘焙的最小配置（生产默认值）
## 所有键均可被环境变量覆盖（点号换下划线转大写），
## 例如 environment.url -> ENVIRONMENT_URL
[configuration.environment]
url = "http://localhost/"
require_ssl = false
certificate_authorities = "/etc/ssl/certs/ca-certificates.crt"
redis = "redis://localhost:6379"

[configuration.server]
rails_environment = "production"
listen = "tcp://0.0.0.0:80"

[configuration.privacy.statistics]
user_counts = true
post_counts = true
comment_counts = true

4.3 数据库配置模板（build/database.yml，ERB 环境变量插值）

production:
  adapter: postgresql
  host: <%= ENV.fetch("DATABASE_HOST", "db") %>
  port: <%= ENV.fetch("DATABASE_PORT", 5432) %>
  username: <%= ENV.fetch("DATABASE_USER", "diaspora") %>
  password: <%= ENV.fetch("DATABASE_PASSWORD", "q1w2e3r4") %>
  encoding: unicode
  database: <%= ENV.fetch("DATABASE_NAME", "diaspora_production") %>
  pool: 5

4.4 入口脚本（build/entrypoint.sh）

#!/bin/bash
set -e

# 用 libjemalloc 降低内存占用（与官方 script/server 行为一致）
JEMALLOC=$(ldconfig -p | grep jemalloc | tr ' ' '\n' | grep '^/' | head -1)
if [ -n "$JEMALLOC" ]; then
  export LD_PRELOAD="$JEMALLOC"
fi

# 等待 PostgreSQL 就绪
if [ -n "$DATABASE_HOST" ]; then
  echo "Waiting for PostgreSQL at ${DATABASE_HOST}:${DATABASE_PORT:-5432} ..."
  until bash -c "echo > /dev/tcp/${DATABASE_HOST}/${DATABASE_PORT:-5432}" 2>/dev/null; do
    sleep 1
  done
fi

# 仅 web 服务执行建库/迁移，避免与 sidekiq 竞争
if [ "$RUN_MIGRATIONS" = "1" ]; then
  bin/rake db:prepare
fi

exec "$@"

db:prepare 幂等（库不存在则建库+迁移，存在则补迁移），升级时同样安全。

4.5 构建镜像

docker build -f build/Dockerfile -t diaspora-app:0.9.1.0 .

实测结果：diaspora-app:0.9.1.0，镜像 ID 397b3df9b0db，大小 2.16 GB；其中 assets:precompile 耗时 33.4 s，bundle install 是最大耗时项。首次构建在 bundle install 阶段失败于 idn-ruby (0.1.5) 原生扩展（twitter-text 依赖），补装 libidn-dev 后通过（见第十一节排障 1）。

4.6 docker-compose.yml

name: diaspora-0.9.1.0-stack
services:
  web:
    image: diaspora-app:0.9.1.0
    build:
      context: .
      dockerfile: build/Dockerfile
    restart: unless-stopped
    ports:
      - "8143:443"
    environment:
      ENVIRONMENT_URL: "https://pod.example.com/"
      ENVIRONMENT_REDIS: "redis://redis:6379"
      ENVIRONMENT_REQUIRE_SSL: "true"
      ENVIRONMENT_CERTIFICATE_AUTHORITIES: "/diaspora/config/certs/ca-combined.pem"
      SERVER_LISTEN: "ssl://0.0.0.0:443?key=/diaspora/config/certs/pod.example.com.key&cert=/diaspora/config/certs/pod.example.com.crt"
      DATABASE_HOST: db
      DATABASE_USER: diaspora
      DATABASE_PASSWORD: q1w2e3r4
      RUN_MIGRATIONS: "1"
      SETTINGS_CAPTCHA_ENABLE: "false"
      SETTINGS_USERNAME_BLACKLIST: "administrator,hostmaster,info,postmaster,root,ssladmin,ssladministrator,sslwebmaster,sysadmin,webmaster,support,contact"
    depends_on:
      - db
      - redis
    networks:
      diaspora:
        aliases:
          - pod.example.com
    volumes:
      - ./data/uploads:/diaspora/public/uploads
      - ./data/certs:/diaspora/config/certs:ro

  sidekiq:
    image: diaspora-app:0.9.1.0
    command: bin/bundle exec sidekiq
    restart: unless-stopped
    environment:
      ENVIRONMENT_URL: "https://pod.example.com/"
      ENVIRONMENT_REDIS: "redis://redis:6379"
      ENVIRONMENT_REQUIRE_SSL: "true"
      ENVIRONMENT_CERTIFICATE_AUTHORITIES: "/diaspora/config/certs/ca-combined.pem"
      DATABASE_HOST: db
      DATABASE_USER: diaspora
      DATABASE_PASSWORD: q1w2e3r4
    depends_on:
      - web
    networks:
      - diaspora
    volumes:
      - ./data/certs:/diaspora/config/certs:ro

  db:
    image: docker.io/library/postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_DB: diaspora_production
      POSTGRES_USER: diaspora
      POSTGRES_PASSWORD: q1w2e3r4
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - diaspora

  redis:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./data/redis:/data
    networks:
      - diaspora

networks:
  diaspora:
    ipam:
      config:
        - subnet: 10.89.68.0/24

三个设计点：

puma 直接 ssl:// 绑定，容器内不跑 nginx，TLS 终结在 puma（0.9.0.0 起官方应用服务器为 puma，原生支持 ssl:// bind）；
compose 网络别名 pod.example.com 指向 web 容器：同宿主多 pod 联邦测试时，容器内 DNS 直接命中，无需改 /etc/hosts；生产环境该别名仅用于容器互访，公网解析由你的 DNS 负责；
SETTINGS_USERNAME_BLACKLIST 去掉了 admin（默认黑名单含 admin/administrator/root 等，实测注册 admin 回显 Username is reserved；生产建议保留默认黑名单，此处仅为测试账号）。

4.7 首次启动

$ docker compose up -d
 Container diaspora-0910-stack-db-1 Started
 Container diaspora-0910-stack-redis-1 Started
 Container diaspora-0910-stack-web-1 Started
 Container diaspora-0910-stack-sidekiq-1 Started

注意：compose 项目名 diaspora-0.9.1.0-stack 被规范化为容器前缀 diaspora-0910-stack-*（点号被剥离）。

web 首启由 entrypoint 自动跑 bin/rake db:prepare，迁移逐条执行至 == 20230604015559 RemoveStripExifFromUsers: migrated，随后 puma 监听：

Puma starting in single mode...
* Puma version: 7.2.0 ("On The Corner")
* Ruby version: ruby 3.3.13 (2026-10-23 revision af48f08f21) [x86_64-linux]
* Environment: production
* Listening on http://0.0.0.0:80

（切 HTTPS 后此行为 * Listening on ssl://0.0.0.0:443?...，且日志出现 Rack::SSL is enabled。）

sidekiq 启动日志注册 7 个 sidekiq-cron 作业：check_birthday、clean_cached_files、cleanup_old_exports、cleanup_pending_photos、queue_users_for_removal、recheck_scheduled_pods、recurring_pod_check，并连接 redis://redis:6379。

无害告警（记录备查）：WARNING: Namespace production not found in /diaspora/config/diaspora.toml——TOML 只有 configuration 命名空间，属预期。

4.8 注册账号并提权管理员

注册实测（关闭 captcha 后 curl 可直接走通；生产开启 captcha 时请浏览器注册）：

curl -c jar http://localhost:8143/users/sign_up   # 200，提取 authenticity_token
curl -b jar -X POST http://localhost:8143/users \
  --data-urlencode "authenticity_token=$TOKEN" \
  --data-urlencode "user[username]=admin" \
  --data-urlencode "user[email]=admin@pod.example.com" \
  --data-urlencode "user[password]=q1w2e3r4" \
  --data-urlencode "user[password_confirmation]=q1w2e3r4"
# POST /users -> 302 redirect=http://localhost:8143/getting_started

diaspora* 没有「设为管理员」的 rake 任务（实测 bin/rake -T 确认），官方路径是 rails runner 调 Role.add_admin：

$ docker compose exec -T web bin/rails runner 'u = User.find_by_username("admin"); Role.add_admin(u.person); puts "admin?=#{u.reload.admin?} diaspora_id=#{u.person.diaspora_handle} guid=#{u.person.guid}"'
admin?=true diaspora_id=admin@pod.example.com guid=2ab71dd0b885013fc1726ec7298bc224

实测 GET / 行为：无管理员时 302 → /podmin（podmin 引导页）；有管理员后渲染落地页。

4.9 功能验证

发帖（路由是 POST /status_messages，参数必须嵌套结构；/posts 仅 show/destroy）：

$ curl -b jar -H "Accept: application/json" -X POST http://localhost:8143/status_messages \
    --data-urlencode "authenticity_token=$T" \
    --data-urlencode "status_message[text]=Hello from S8 diaspora test pod!" \
    --data-urlencode "aspect_ids[]=public"
POST json -> 201
{"guid":"23a28bf0b886013fc1726ec7298bc224","public":true,"text":"Hello from S8 diaspora test pod!",
 "author":{"diaspora_id":"admin@pod.example.com", ...}}

端点状态码实测（http://localhost:8143）：

200 /   200 /.well-known/nodeinfo   200 /nodeinfo/2.0   200 /.well-known/host-meta
200 /.well-known/webfinger?resource=acct:admin@pod.example.com
200 /hcard/users/2ab71dd0b885013fc1726ec7298bc224
200 /public/admin.atom

nodeinfo/2.0 实测回显：{"software":{"name":"diaspora","version":"0.9.1.0"},"protocols":["diaspora"],"openRegistrations":true,"usage":{"users":{"total":1,...},"localPosts":1}}。

五、数据持久化

5.1 必须持久化的卷

宿主目录	容器路径	内容	丢失后果
`./data/uploads`	`/diaspora/public/uploads`	用户上传的照片/文件	图片 404
`./data/postgres`	`/var/lib/postgresql/data`	全部业务数据	整站数据丢失
`./data/redis`	`/data`	Sidekiq 队列/缓存	积压作业丢失（可重建）
`./data/certs`	`/diaspora/config/certs`	TLS 证书与 CA 信任库	联邦与 HTTPS 中断

日志（/diaspora/log/production.log、log/sidekiq.log）在容器层，如需长期留存建议再挂 ./data/log。

5.2 会话密钥持久化（生产必做）

本测试镜像把 bin/rake generate:secret_token 的产物（config/initializers/secret_token.rb）烘焙进了镜像。生产环境不应如此：该文件丢失/变更会导致全部用户会话失效、OIDC 应用密钥变化。正确做法是把 config/initializers/secret_token.rb 所在路径挂卷持久化，或在首次启动后从容器内拷出备份。同理，用户 RSA 签名密钥存于数据库 people.private_key，随数据库备份走。

六、环境变量表

6.1 覆盖机制

源码 config/load_config.rb 的 AppConfig 提供者优先级：Env > TOML(diaspora.toml) > defaults.yml。环境变量名 = TOML 点分路径转下划线并大写，例如 environment.url → ENVIRONMENT_URL、server.listen → SERVER_LISTEN、settings.captcha.enable → SETTINGS_CAPTCHA_ENABLE；列表型值用逗号分隔。

6.2 本部署用到的变量

环境变量	对应配置键	示例值	说明
`ENVIRONMENT_URL`	environment.url	`https://pod.example.com/`	pod 对外 URL，联邦身份的基础
`ENVIRONMENT_REQUIRE_SSL`	environment.require_ssl	`true`	true 时插入 Rack::SSL 中间件强制 https
`ENVIRONMENT_CERTIFICATE_AUTHORITIES`	environment.certificate_authorities	`/diaspora/config/certs/ca-combined.pem`	出站联邦请求的信任库，web 与 sidekiq 都要设
`ENVIRONMENT_REDIS`	environment.redis	`redis://redis:6379`	Sidekiq/缓存后端
`SERVER_LISTEN`	server.listen	`ssl://0.0.0.0:443?key=...&cert=...`	puma 绑定串（0.9.0.0 新格式，见 7.2）
`DATABASE_HOST/PORT/USER/PASSWORD/NAME`	（database.yml ERB）	`db` / `5432` / `diaspora` / …	注入 database.yml 模板
`RUN_MIGRATIONS`	（entrypoint 自定义）	`1`	仅 web 设 1，触发 `db:prepare`
`SETTINGS_CAPTCHA_ENABLE`	settings.captcha.enable	`false`	注册图形验证码；生产建议 `true`
`SETTINGS_USERNAME_BLACKLIST`	settings.username_blacklist	`administrator,info,...`	保留用户名黑名单（默认含 admin/root 等）

七、配置参数说明

7.1 关键 TOML 参数

environment.url：必须与用户实际访问的 URL 一致（含末尾 /），它决定 diaspora_id 的域名部分与联邦签名实体里的 pod_uri；上线后不可更改域名（官方文档：http→https 改协议无后果，域名不可改）；
environment.require_ssl：生产必须 true（Rack::SSL 会把所有 http 请求 301 到 https）；
server.listen：见下节格式；
pod_terms_of_use.*、settings.registrations.open 等按需补充，全部键可在源码 config/defaults.yml 查到默认值。

7.2 puma listen 格式（0.9.0.0 变更）

Changelog 0.9.0.0 明确新格式：

Unix socket 相对路径：unix://tmp/diaspora.sock（旧 unix:tmp/...）；
Unix socket 绝对路径：unix:///run/diaspora/diaspora.sock；
TCP：tcp://127.0.0.1:3000；
TLS：ssl://0.0.0.0:443?key=/path/key&cert=/path/crt（本指南用法，puma 原生终结 TLS）。

八、配置文件挂载

镜像内烘焙的 diaspora.toml / database.yml 适合「全 env 覆盖」模式；若你更习惯改文件，compose 里直接覆盖挂载即可：

    volumes:
      - ./config/diaspora.toml:/diaspora/config/diaspora.toml:ro
      - ./config/database.yml:/diaspora/config/database.yml:ro
      - ./data/uploads:/diaspora/public/uploads
      - ./data/certs:/diaspora/config/certs:ro

注意 TOML 文件里 [configuration.environment] 等命名空间写法与 config/diaspora.toml.example（源码仓库）一致；env 变量始终覆盖文件值，两者混用时以 env 为准。

九、等价 docker run

以下为 compose 的等价展开（按 compose 语义转写，未单独复测；compose 编排仍是推荐方式）：

docker network create --subnet 10.89.68.0/24 diaspora

docker run -d --name diaspora-db --network diaspora \
  -e POSTGRES_DB=diaspora_production -e POSTGRES_USER=diaspora \
  -e POSTGRES_PASSWORD=q1w2e3r4 \
  -v $PWD/data/postgres:/var/lib/postgresql/data postgres:15

docker run -d --name diaspora-redis --network diaspora \
  -v $PWD/data/redis:/data redis:7

docker run -d --name diaspora-web --network diaspora \
  --network-alias pod.example.com -p 8143:443 \
  -e ENVIRONMENT_URL=https://pod.example.com/ \
  -e ENVIRONMENT_REQUIRE_SSL=true \
  -e ENVIRONMENT_CERTIFICATE_AUTHORITIES=/diaspora/config/certs/ca-combined.pem \
  -e SERVER_LISTEN='ssl://0.0.0.0:443?key=/diaspora/config/certs/pod.example.com.key&cert=/diaspora/config/certs/pod.example.com.crt' \
  -e DATABASE_HOST=db -e DATABASE_USER=diaspora -e DATABASE_PASSWORD=q1w2e3r4 \
  -e RUN_MIGRATIONS=1 \
  -v $PWD/data/uploads:/diaspora/public/uploads \
  -v $PWD/data/certs:/diaspora/config/certs:ro \
  diaspora-app:0.9.1.0

docker run -d --name diaspora-sidekiq --network diaspora \
  -e ENVIRONMENT_URL=https://pod.example.com/ \
  -e ENVIRONMENT_REQUIRE_SSL=true \
  -e ENVIRONMENT_CERTIFICATE_AUTHORITIES=/diaspora/config/certs/ca-combined.pem \
  -e DATABASE_HOST=db -e DATABASE_USER=diaspora -e DATABASE_PASSWORD=q1w2e3r4 \
  -v $PWD/data/certs:/diaspora/config/certs:ro \
  diaspora-app:0.9.1.0 bin/bundle exec sidekiq

十、常用运维命令

docker compose ps                          # 服务状态
docker compose logs -f web                 # web 日志
docker compose logs -f sidekiq             # 后台作业日志
docker compose exec -T web bin/rails runner 'puts "users=#{User.count} posts=#{StatusMessage.count}"'
docker compose exec -T db pg_dump -U diaspora diaspora_production > backup.sql   # 备份
docker compose up -d --build               # 改 Dockerfile 后重建
docker compose down                        # 停止（数据卷保留）

日志、备份、升级的完整流程见本专栏运维篇。

十一、常见问题（实测排障实录）

bundle install 失败于 idn-ruby (0.1.5) 原生扩展（twitter-text 依赖）：镜像缺 libidn-dev。在 apt 清单加入 libidn-dev（连同 cmake libcurl4-openssl-dev libmagickwand-dev libxml2-dev libxslt1-dev，对齐官方 dev Dockerfile）后构建通过。
注册 admin 回显 Username is reserved：默认 settings.username_blacklist 含 admin/administrator/root/info/support/contact 等（config/defaults.yml）。测试栈用 SETTINGS_USERNAME_BLACKLIST 逗号列表覆盖（去掉 admin、保留其余）；生产保留默认黑名单。
注册页默认开图形验证码（settings.captcha.enable=true），curl 无法自动过：测试用 SETTINGS_CAPTCHA_ENABLE=false 关闭，生产开启并走浏览器注册。
重启 web 后过早 curl 得 000/connection refused：puma eager_load 约 10 s 后才开始监听。无 healthcheck 的脚本化验证必须轮询等待。
curl 发帖「看起来成功」但 DB 没有：传扁平 text= 时控制器取 params[:status_message][:text] 得 nil 报错；Accept: */* 走 mobile 分支返回 302 回 /stream（假成功），Accept: application/json 才暴露错误。正确姿势：嵌套参数 status_message[text]=... + aspect_ids[]=public，并用 JSON Accept 或查 DB 核实。
CSRF token 提取为空、POST 被弹回 sign_in：token 必须与登录会话同源——同一 cookie jar 先登录、再 GET /stream 取 token、同 jar POST。
sidekiq 崩溃循环 FATAL: Diaspora doesn't know where your certificate authorities are：sidekiq 服务设了 ENVIRONMENT_CERTIFICATE_AUTHORITIES 但忘挂 ./data/certs 卷。web 正常而 sidekiq 死时，出站联邦作业全部滞留 Redis 队列；补挂卷重启后积压作业立刻被消费（Workers::Deferred/SendPrivate done）。
/statistics 返回 406：控制器对 format.json 故意 head :not_acceptable（node_info_controller.rb），非故障；Accept: text/html 得 200 统计页，机器可读统计走 /nodeinfo/2.0。
http-only 部署后与其他 pod 联邦失败（DiscoveryError）：WebFinger 永远先请求 https://域名/.well-known/webfinger，http 回退仅 development。生产必须 TLS，见 3.1。

十二、参考链接

《diaspora* 介绍与选型指南》（本专栏认知篇）
源码与 Releases：https://github.com/diaspora/diaspora
Changelog 0.9.0.0（puma/TOML/yarn/Ruby 3.3）：https://github.com/diaspora/diaspora/blob/main/Changelog.md
官方安装文档源（dev 镜像不可生产）：https://github.com/diaspora/north-star
官方 wiki 安装页：https://wiki.diasporafoundation.org/Installation
配置示例 config/diaspora.toml.example（源码仓库内）