diaspora* 日常运维手册

本文是 diaspora* 专栏的运维篇，基于 0.9.1.0 生产形态 Docker Compose 部署（部署过程与文件见 《diaspora* Docker Compose 部署指南》，组件认知见 《diaspora* 介绍与选型指南》）。文中命令与回显均为 2026-11-02 实测逐字记录，pod 域名以 pod.example.com 占位，示例管理员账号 admin@pod.example.com / q1w2e3r4。

一、运维环境信息

1.1 被管对象

• 应用：diaspora* 0.9.1.0（Rails 6.1.7.10 / Puma 7.2.0 / Sidekiq 7.3.10 / Ruby 3.3）；
• 编排：compose 项目 diaspora-0.9.1.0-stack，容器前缀被规范化为 diaspora-0910-stack-*（点号剥离，运维脚本注意）；
• 容器：web（puma，ssl://0.0.0.0:443，宿主 8143）、sidekiq、db（postgres:15）、redis（redis:7）。

1.2 资源基线（空载实测）

docker stats 实测：

puma 单 worker 即可（官方 Changelog 0.9.0.0：With Puma, there should not be a need to increase the number of workers above a single worker in any pod of any size），内存增长主要看用户量，容量规划按 1 GB 起步、2 GB 富余。

1.3 进程职责边界

• web：页面、REST API、联邦入站端点（/receive、/fetch、webfinger/hcard）；
• sidekiq：出站联邦投递（Salmon 推送）、7 个 cron 定时作业、照片清理、导出、账号移除队列；
• 判断法则：入站问题查 web 日志，出站/延迟问题查 sidekiq 与 Redis 队列——两者故障表现完全不同（见第八节排障 1）。

二、管理面板与入口

2.1 管理员登录

https://pod.example.com/users/sign_in，用户名填全量 diaspora_id（admin@pod.example.com，不是裸 admin），实测登录成功 302 → /stream。

2.2 管理路由实测清单

以下路径均以管理员会话实测（源码 config/routes.rb 的 admin 约束为 warden user.admin?）：

用户管理动作只有 POST 端点（面板按钮背后即这些路由）：/admin/users/:id/make_admin、remove_admin、make_moderator、remove_moderator、lock_account、unlock_account、close_account、make_spotlight、remove_spotlight。

2.3 新用户/无管理员状态

实测 GET /：pod 内没有任何管理员时 302 → /podmin（podmin 引导页，home_controller.rb）；产生管理员后渲染落地页。首次部署完成后务必先注册并提权（提权命令见部署篇 4.8——没有 make_admin 的 rake 任务，官方路径是 Role.add_admin）。

三、日常巡检

3.1 服务健康（30 秒清单）

docker compose ps                                  # 4 容器全 Up
docker compose logs --tail=50 sidekiq              # 无 FATAL/崩溃循环
curl -sk https://localhost:8143/.well-known/nodeinfo -o /dev/null -w '%{http_code}\n'   # 200
curl -sk https://localhost:8143/nodeinfo/2.0       # version 与预期一致

注意：重启 web 后 puma eager_load 约 10 秒才开始监听，过早探测得 000/connection refused 属正常（实测），巡检脚本应轮询而非单次判定。

3.2 联邦健康

# 发现链路：webfinger → hcard（域名换成你的 pod）
curl -sk "https://localhost:8143/.well-known/webfinger?resource=acct:admin@pod.example.com"
curl -sk https://localhost:8143/hcard/users/<guid>
# 公开 Atom 流
curl -sk https://localhost:8143/public/admin.atom | head -5

出站健康看 sidekiq：/sidekiq 面板或 Redis 队列长度：

docker compose exec -T redis redis-cli llen sidekiq:default

队列持续增长且 web 正常 → 优先怀疑 sidekiq（证书卷、DNS、对端 pod 失联）。

3.3 pod 网络状态维护

/admin/pods 页列出数据库已知 pod，可逐个 recheck；自动侧由 cron 作业 recheck_scheduled_pods、recurring_pod_check 定期复检（sidekiq 启动日志实测注册这 7 个 cron 作业：check_birthday、clean_cached_files、cleanup_old_exports、cleanup_pending_photos、queue_users_for_removal、recheck_scheduled_pods、recurring_pod_check）。

3.4 统计口径

• /statistics：Accept: text/html 返回 200 渲染统计页；对 JSON 返回 406 是控制器故意行为（node_info_controller.rb 的 format.json { head :not_acceptable }），不是故障；
• 机器可读统计走 /nodeinfo/2.0（实测含 users.total、localPosts）；
• 0.9.0.0 起 nodeinfo 端点带 CORS 头，支持浏览器端直接抓取。

四、日志与观测

4.1 日志位置

• Rails：容器内 /diaspora/log/production.log（实测空载 pod 运行 45 分钟仅 8.8 KB，量级很小）；
• Sidekiq：/diaspora/log/sidekiq.log（配置默认值）；
• 容器视角：docker compose logs [-f] web|sidekiq|db|redis。

4.2 日志轮转

应用不自带轮转，长周期运行建议宿主机 logrotate 或挂 ./data/log 卷后统一处理；docker json-file 日志默认无上限，compose 可加：

    logging:
      driver: json-file
      options: { max-size: "10m", max-file: "3" }

4.3 已知无害告警（实测记录）

• WARNING: Namespace production not found in /diaspora/config/diaspora.toml：TOML 仅含 configuration 命名空间，属预期；
• Ruby 3.4 默认 gem 移除预告（mutex_m/syslog）：来自 activesupport/logging，不影响 3.3 运行。

五、备份与恢复

5.1 官方要求：三件套

官方安装文档（north-star finalize_server）逐字要求备份：数据库全量 dump + public 目录（用户上传）+ config 目录（配置与加密/会话密钥），并建议整目录备份。对应本部署：

5.2 备份命令（实测）

# 1) 数据库（一致性快照，无需停服）
docker compose exec -T db pg_dump -U diaspora diaspora_production | gzip > diaspora-db-$(date +%F).sql.gz

# 2) 上传目录
tar czf diaspora-uploads-$(date +%F).tar.gz -C data uploads

# 3) 证书与配置（含 secret_token.rb，若走挂载方案）
tar czf diaspora-conf-$(date +%F).tar.gz data/certs build/diaspora.toml build/database.yml

cron 每日示例（宿主机 crontab）：

17 3 * * * cd /srv/diaspora && docker compose exec -T db pg_dump -U diaspora diaspora_production | gzip > /backup/diaspora-db-$(date +\%F).sql.gz

5.3 恢复流程

1. 起空栈（db/redis 先上），恢复 data/uploads、data/certs 与配置文件；
2. 建库并灌入：createdb -U diaspora diaspora_production（或让 db:prepare 建空库后）gunzip -c backup.sql.gz | docker compose exec -T db psql -U diaspora -d diaspora_production；
3. 以 RUN_MIGRATIONS=1 启动 web（db:prepare 幂等，库存在则补迁移）；
4. 验证：登录、/nodeinfo/2.0、webfinger。

secret_token.rb 与数据库必须同批恢复：只恢复库不恢复密钥，全部会话失效；只恢复密钥不恢复库，新库会生成不同密钥——备份三件套缺一不可。

六、升级

6.1 官方硬性要求

官方文档（initialize/finalize_server）明确：每次更新代码后必须重新预编译静态资源。升级 = 换镜像 tag + 跑迁移 + 预编译：

bin/rake db:migrate            # 或依赖 entrypoint 的 db:prepare（RUN_MIGRATIONS=1）
bin/rake assets:precompile     # 每次更新后必须

6.2 Compose 升级步骤（以 0.9.1.0 → 未来 0.9.x 为例）

# 1) 先做第五节三件套备份
# 2) 更新构建上下文源码目录与 tar 包，改 Dockerfile/compose 中的 tag
sed -i 's/0\.9\.1\.0/0.9.2.0/g' docker-compose.yml
docker compose build
# 3) 滚动重启：web 先迁移，sidekiq 后起
docker compose up -d web
sleep 15 && docker compose up -d sidekiq
# 4) 验证
docker compose logs --tail=30 web | grep -E 'Migrating|Listening'
curl -sk https://localhost:8143/nodeinfo/2.0 | grep version

6.3 版本跟踪

发布节奏偏慢（0.9.0.0→0.9.1.0 约 22 个月），0.9.1.0 属安全修复版（修复 OIDC API SSRF）。订阅 https://github.com/diaspora/diaspora/releases.atom 即可；安全通告优先升级。大版本 1.0 将移除旧 YAML 配置读取（Changelog 0.9.0.0 预告），届时先完成 TOML 迁移。

七、用户与内容管理

7.1 检索与处置

/admins/user_search 按用户名/邮箱/diaspora_id 检索，处置动作即 2.2 节的 POST 端点：锁定（lock_account，用户无法登录但数据保留）、关闭（close_account，进移除队列）、设为管理员/版主/spotlight。

7.2 账号移除队列

关闭的账号不即时删除，由 cron queue_users_for_removal 定期入队，最终删除。手动触发：

docker compose exec -T web bin/rake maintenance:queue_users_for_removal

7.3 群发通告

podmin 向用户群发通知邮件的官方 rake 任务：

docker compose exec -T web bin/rake 'podmin:admin_mail[users_def,msg_path,subject]'
# users_def：用户筛选定义；msg_path：正文文件；subject：邮件主题

（bin/rake -T 实测列出的自定义任务全集：accounts:migration[...]、maintenance:queue_users_for_removal、podmin:admin_mail[...]、generate:secret_token、assets:precompile/clobber、db:* 全家桶。）

7.4 举报处理

0.9.1.0 起管理端举报总览显示违规内容作者，配合 /admin/users/:id/lock_account 快速处置。

八、常见故障处置（实测排障实录）

1. sidekiq 崩溃循环、联邦出站全停：日志逐字 FATAL: Diaspora doesn't know where your certificate authorities are. Please ensure they are set to a valid path in diaspora.yml，且因 restart: unless-stopped 反复重启（日志刷 3 遍 Waiting for PostgreSQL + FATAL）。根因：sidekiq 服务设置了 ENVIRONMENT_CERTIFICATE_AUTHORITIES 但忘挂 certs 卷——web 正常而 sidekiq 死，出站作业滞留 Redis。修复：补 - ./data/certs:/diaspora/config/certs:ro，重启后积压作业立刻被消费（实测 Workers::SendPrivate done）。
2. 重启 web 后连接拒绝：puma eager_load 约 10 s 才监听（实测），等待后自愈；监控加轮询。
3. rails runner 报 Please specify a valid ruby command：多语句含空格/引号经 docker compose exec 传递被拆词。稳妥写法：单语句，或把脚本写成文件经 stdin 喂入：docker compose exec -T web bin/rails runner /dev/stdin < script.rb。
4. 网页发帖「成功」但库里没有：扁平 text= 参数 + Accept: */* 走 mobile 分支返回 302 假成功；正确为嵌套参数 status_message[text]= + aspect_ids[]=public 并用 JSON Accept 核实 201（详见部署篇 FAQ 5）。
5. 收不到远程 pod 的更新（DiscoveryError）：对端或本端 http-only——WebFinger 永远先走 https，生产必须 TLS（部署篇 3.1）。
6. 注册报 Username is reserved：命中 settings.username_blacklist 默认名单（admin/root/info/support 等），属保护行为，非故障。

九、安全维护

1. 证书轮换：测试自签服务器证书实测 825 天有效期；生产用受信 CA 证书到期前轮换后，docker compose restart web sidekiq 即生效（puma 启动时加载 key/cert）。出站信任库 ca-combined.pem 若含自签测试 CA，公网部署应改回纯系统 CA 包。
2. 密钥管理：config/initializers/secret_token.rb（会话）与数据库内 people.private_key（联邦签名）都纳入备份；镜像内烘焙密钥仅适合测试栈（部署篇 5.2）。
3. 安全通告：0.9.0.0 修复 2FA 暴力破解（CVE-2024-0227）、0.9.1.0 修复 OIDC SSRF——历史漏洞提示保持版本更新比任何加固都重要；CSP 自 0.9.0.0 起默认开启。
4. 注册策略：小圈子 pod 建议关闭开放注册改邀请制（settings.registrations.open=false，面板邀请入口 /users/invitations），保留 captcha 与默认用户名黑名单。

十、参考链接

• 《diaspora* 介绍与选型指南》
• 《diaspora* Docker Compose 部署指南》
• 源码仓库与 Changelog：https://github.com/diaspora/diaspora
• 官方文档源仓库（安装/finalize_server/备份要求）：https://github.com/diaspora/north-star
• 官方 wiki：https://wiki.diasporafoundation.org/
• Sidekiq 控制台文档：https://sidekiq.org/
• Releases 订阅：https://github.com/diaspora/diaspora/releases.atom