Fider v0.38.2 日常运维手册

目标：为已按《Fider v0.38.2 Docker Compose 部署指南》上线的 Fider 实例建立日常巡检、备份恢复、监控告警、扩缩容与升级回滚的标准操作路径。本文全部命令与回显均在运行中的实验环境实测照抄（取证日期 2026-11-01），升级与回滚在数据库副本上实测完成，未触碰生产主库。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）；Docker Compose v5.6.1
Fider：getfider/fider:v0.38.2（容器 fider-v0.38.2-server，版本横幅实测 v0.38.2-e492af4a30db30c104df3dfb9e0f04e55757ba9e，对外端口 8140，容器内监听 3000）
PostgreSQL：postgres:17（容器 fider-v0.38.2-db，实测服务端 PostgreSQL 17.11 (Debian 17.11-1.pgdg13+2)，数据目录 bind mount /opt/fider/pg_data）
试用 SMTP：mailhog/mailhog（容器 fider-v0.38.2-mailhog，UI 端口 8142，收件端口 1025）
站点：单租户 quzuo（tenants 表实测 1 行，subdomain=default，status=1）；管理员 root@quzuo.net
部署目录：/opt/fider（compose 文件与备份目录统一收敛于此）
数据库规模基线（实测）：fider 库 24 张表、95 条迁移记录（最高版本 202606121200）、库大小 9254 kB

💡 说明：本文所有 docker 命令均在部署目录 /opt/fider 下执行（docker compose 子命令需读取 compose 文件）；docker exec 类命令任意目录可执行。

二、日常巡检

巡检回答三个问题：进程活着吗（L1）、业务闭环吗（L2）、数据面正常吗（L3）。以下命令全部实测。

2.1 L1 存活巡检：ping 与 /_health

Fider 二进制内置 ping 子命令，本质是向本机 /_health 发 GET 并按结果返回退出码：

docker exec fider-v0.38.2-server /app/fider ping; echo "ping_exit=$?"

实测回显：

ping_exit=0

HTTP 层直接探测对外端点：

curl -s -w "\nHTTP %{http_code}\n" http://192.168.1.172:8140/_health

实测回显：

{"status":"Healthy"}
HTTP 200

💡 说明：ping 退出码 0 即健康、非 0 即异常。实验环境的 app 容器配置了以该命令为探针的健康检查（实测 docker inspect 的 Healthcheck.Test 为 ["CMD-SHELL","./fider ping"]、Timeout 5s），docker compose ps 的 (healthy) 状态可直接作为巡检第一眼看板。

2.2 L2 业务巡检：服务状态与访问日志

cd /opt/fider && docker compose ps

实测回显：

NAME                   IMAGE                    COMMAND                  SERVICE   CREATED       STATUS                      PORTS
fider-v0.38.2-db       postgres:17              "docker-entrypoint.s…"   db        2 hours ago   Up 2 hours (healthy)        5432/tcp
fider-v0.38.2-server   getfider/fider:v0.38.2   "/bin/sh -c './fider…"   app       2 hours ago   Up About an hour (healthy)   0.0.0.0:8140->3000/tcp, [::]:8140->3000/tcp

近段访问日志（判读请求是否正常收尾）：

docker logs --tail 6 fider-v0.38.2-server 2>&1

实测回显（节选）：

INFO [2026-11-01T12:40:49Z] [WEB] http server started on :3000
INFO [2026-11-01T12:40:54Z] [WEB] GET http://192.168.1.172:8140/api/v1/posts started
INFO [2026-11-01T12:40:55Z] [WEB] GET http://192.168.1.172:8140/api/v1/posts finished with 200 in 7ms (committed)
INFO [2026-11-01T12:40:55Z] [WEB] GET http://192.168.1.172:8140/ started
INFO [2026-11-01T12:40:55Z] [WEB] GET http://192.168.1.172:8140/ finished with 200 in 8ms (committed)

判读要点：出现 finished with 200 in 7ms (committed) 这类正常收尾行即业务面健康；出现 ERROR 行或 [MIGRATE] 反复刷屏（根因实录见《Fider v0.38.2 故障排查与 FAQ》第三章）需立即介入。

2.3 L3 数据面巡检：迁移版本、业务量与库大小

docker exec fider-v0.38.2-db psql -U fider -d fider -tc "select count(*) as mig_count, max(version) as last_mig from migrations_history;" -tc "select pg_size_pretty(pg_database_size('fider'));" -tc "select (select count(*) from tenants) t, (select count(*) from users) u, (select count(*) from posts) p, (select count(*) from comments) c, (select count(*) from post_votes) pv, (select count(*) from blobs) b;"

实测回显：

        95 | 202606121200

 9254 kB

 1 | 1 | 1 | 0 | 1 | 0

判读要点：mig_count/last_mig 应与当前镜像版本匹配（v0.38.2 为 95 条，实测 stable 构建同为 95 条；见 6.2）；blobs 计数即 BLOB_STORAGE=sql 模式下的附件存量，持续增长时对照磁盘余量。表名注意：投票表是 post_votes（实测直接查 votes 报 ERROR: relation "votes" does not exist）。

2.4 资源水位

docker stats --no-stream --format '{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}' fider-v0.38.2-server fider-v0.38.2-db fider-v0.38.2-mailhog

实测回显：

fider-v0.38.2-server	0.00%	17.24MiB / 15.57GiB
fider-v0.38.2-db	0.00%	55.52MiB / 15.57GiB
fider-v0.38.2-mailhog	0.00%	7.457MiB / 15.57GiB

Go 单二进制应用侧仅约 17 MiB 常驻，内存大头在 PostgreSQL；小站 1 核 1GB 的虚拟机即可承载（以上为空闲水位实测，压测口径另议）。

三、备份与恢复

Fider 全部状态（含上传附件，默认 BLOB_STORAGE=sql）都在 PostgreSQL 单库内，备份 = pg_dump，恢复 = psql 灌回。

3.1 逻辑备份（pg_dump 实测）

cd /opt/fider/backup
docker exec fider-v0.38.2-db pg_dump -U fider -d fider -Fp > fider-$(date +%Y%m%d)-ops.sql
ls -la fider-$(date +%Y%m%d)-ops.sql

实测回显：

-rw-r--r-- 1 root root 99217 Nov  1 22:11 fider-20261101-ops.sql

导出文件首尾完整性检查：

head -3 fider-20261101-ops.sql; tail -1 fider-20261101-ops.sql

实测回显：

--
-- PostgreSQL database dump
--
\unrestrict oj9AiPuVe3R8VzaRGFUUmdcmeFqnKMdPzQxx1RfKpzqnWIryJoVZXtIp5aCjoai

💡 说明：-Fp 输出纯 SQL 文本（可 grep、可人工审阅）；数据量大后可换 -Fc 自定义压缩格式配合 pg_restore 并行恢复。转储末尾以 \unrestrict 开头、后跟随机令牌的行是 PG 17 逻辑备份的正常收尾标记（见 3.1 实测回显），缺它说明导出被截断。

3.2 定时备份（推荐 cron 配置）

以下 crontab 为推荐配置（每日 02:10 全量、保留 7 天）：

crontab -l 2>/dev/null | grep -v fider- > /tmp/cron.new; cat >> /tmp/cron.new <<'EOF'
10 2 * * * cd /opt/fider && docker exec fider-v0.38.2-db pg_dump -U fider -d fider -Fp | gzip > /opt/fider/backup/fider-$(date +\%F).sql.gz && find /opt/fider/backup -name 'fider-*.sql.gz' -mtime +7 -delete
EOF
crontab /tmp/cron.new && crontab -l | grep fider-

⚠️ 注意：crontab 行内 % 必须转义为 \%（否则被 cron 当作换行）；上式与 3.1 的单次导出命令同源，仅加了 gzip 轮转。

3.3 恢复演练（异库恢复实测）

恢复验证的原则：先恢复到旁路库，确认数据完整，再考虑覆盖主库。本实验环境实测流程：

# 1) 建旁路库
docker exec fider-v0.38.2-db psql -U fider -d postgres -c "CREATE DATABASE fider_restore OWNER fider;"

实测回显：

CREATE DATABASE

# 2) 灌入转储文件（ON_ERROR_STOP 保证遇错即停）
cd /opt/fider/backup
docker exec -i fider-v0.38.2-db psql -U fider -d fider_restore -v ON_ERROR_STOP=1 < fider-20261101-ops.sql > restore-ops.log 2>&1
echo "restore_exit=$?"; tail -3 restore-ops.log

实测回显：

restore_exit=0
ALTER TABLE
ALTER TABLE
ALTER TABLE

# 3) 核对旁路库数据与主库一致
docker exec fider-v0.38.2-db psql -U fider -d fider_restore -tc "select count(*) from migrations_history;" -tc "select (select count(*) from tenants) t, (select count(*) from posts) p, (select title from posts limit 1);"

实测回显：

    95

 1 | 1 | 支持中文全文检索

迁移记录 95 条、站点 1 个、帖子标题与主库完全一致，恢复链路验证通过。演练通过后清理旁路库：

docker exec fider-v0.38.2-db psql -U fider -d postgres -c "DROP DATABASE fider_restore;"

3.4 主库灾难恢复（停栈灌回）

主库损坏需整体回滚时（实测环境不执行，流程为标准操作）：

cd /opt/fider
docker compose stop app
docker exec fider-v0.38.2-db psql -U fider -d postgres -c "DROP DATABASE fider;" -c "CREATE DATABASE fider OWNER fider;"
docker exec -i fider-v0.38.2-db psql -U fider -d fider -v ON_ERROR_STOP=1 < /opt/fider/backup/fider-20261101-ops.sql
docker compose start app
docker exec fider-v0.38.2-server /app/fider ping; echo $?

应用启动命令为 ./fider migrate && ./fider，恢复旧转储后 migrate 会按 migrations_history 自动补齐缺失迁移，无需手工干预。

四、监控与告警

4.1 健康探针（编排层）

compose 的 app 服务加同款 ./fider ping 健康检查即可让 docker compose ps/编排系统自动摘除不健康实例（实验环境运行容器即此配置）：

  app:
    healthcheck:
      test: ["CMD-SHELL", "./fider ping"]
      timeout: 5s

实测 docker inspect 回显（节选）：

{"Test":["CMD-SHELL","./fider ping"],"Timeout":5000000000}

健康记录逐 30 秒滚动、ExitCode 0（实测 State.Health.Log 最近 5 条全 0，FailingStreak:0）。

4.2 Prometheus 指标（实测开启）

二进制内置指标开关（实测环境变量名：METRICS_ENABLED/METRICS_HOST/METRICS_PORT，指标端口默认 4000）。一次性容器实测：

docker run -d --name fider-metrics-test --network fider-v0382-stack_fider-net \
  -p 8148:3000 -p 8149:4000 \
  -e BASE_URL="http://192.168.1.172:8148" \
  -e DATABASE_URL="postgres://fider:***@db:5432/fider?sslmode=disable" \
  -e JWT_SECRET="3f9c2a7e5b1d8c4a6f0e9b2c5d8a1f4e7b0c3d6a9f2e5b8c1d4a7e0f3b6c9d2" \
  -e EMAIL_NOREPLY="noreply@quzuo.net" -e EMAIL_SMTP_HOST="mailhog" -e EMAIL_SMTP_PORT="1025" \
  -e METRICS_ENABLED="true" \
  getfider/fider:v0.38.2
curl -s http://192.168.1.172:8149/metrics | head -14

实测抓取回显（节选）：

# HELP fider_comments_total Number of Fider comments.
# TYPE fider_comments_total counter
fider_comments_total 0
# HELP fider_info Information about Fider environment.
# TYPE fider_info gauge
fider_info{version="v0.38.2-e492af4a30db30c104df3dfb9e0f04e55757ba9e"} 1
# HELP fider_posts_total Number of Fider posts.
# TYPE fider_posts_total counter
fider_posts_total 0
# HELP fider_tenants_total Number of Fider tenants.
# TYPE fider_tenants_total counter
fider_tenants_total 0

⚠️ 实测坑：fider_posts_total/fider_tenants_total 在该次抓取中为 0，而库里实有 1 站点 1 帖——指标计数口径与业务表行数不同步（疑似只统计"已批准/公开可见"维度），做告警阈值前先对照 psql 计数校准，勿直接拿指标值当业务量。测试容器已 docker rm -f 清理。

生产接入：给主栈 app 服务加 METRICS_ENABLED: "true" 并暴露 4000 端口（仅对内网 Prometheus 开放，勿映射公网）。

4.3 SQL 日志通道（logs 表）

Fider 会把运行日志写入 logs 表（实测本环境默认已写入 149 条），可直接 SQL 检索：

docker exec fider-v0.38.2-db psql -U fider -d fider -c "select id, tag, level, left(text,90) as text from logs order by id desc limit 6;"

实测回显（节选）：

 id  | tag | level |                                      text
-----+-----+-------+---------------------------------------------------------------------------------
 149 | WEB | INFO  | GET http://192.168.1.172:8140/ finished with 200 in 8ms (committed)
 148 | WEB | INFO  | GET http://192.168.1.172:8140/ started
 147 | WEB | INFO  | GET http://192.168.1.172:8140/api/v1/posts finished with 200 in 7ms (committed)
 145 | BGW | INFO  | Starting worker 4.

告警建议：select count(*) from logs where level='ERROR' and created_at > now() - interval '10 min'; 非零即告警（表列名实测为 tag/level/text/properties/created_at）。

4.4 邮件通道巡检

试用环境经 MailHog API 数邮件（生产改在真实 SMTP 侧计数）：

curl -s http://192.168.1.172:8142/api/v2/messages | python3 -c "import json,sys; d=json.load(sys.stdin); print('total:', d['total'])"

实测回显：

total: 3

五、扩缩容与容量规划

Fider 应用侧无状态（上传文件默认入库），容量瓶颈按序出现在：PostgreSQL 磁盘 → 应用内存 → SMTP 吞吐。

纵向扩容（首选）：应用容器常驻仅约 17 MiB（2.4 实测），给 PostgreSQL 加内存/磁盘收益最直接；docker compose down && 调整资源限制 && docker compose up -d 即可，数据在 bind mount 中不随容器销毁；
附件外置：blobs 表增长过快时切 BLOB_STORAGE=s3（配 BLOB_STORAGE_S3_BUCKET/BLOB_STORAGE_S3_REGION/BLOB_STORAGE_S3_ENDPOINT_URL/BLOB_STORAGE_S3_ACCESS_KEY_ID/BLOB_STORAGE_S3_SECRET_ACCESS_KEY，变量名实测取自镜像内二进制）。⚠️ 官方明示切换不迁移存量文件，务必开站初期定方案；
多板合并：一套部署服务多个反馈板时启用 HOST_MODE=multi（子域名隔离），比横向扩实例更符合官方架构；
多实例水平扩展：官方不提供集群方案，应用虽无状态可挂负载均衡，但 PG 主从、任务队列去重均需自行验证——生产规划优先单实例+可靠备份，勿盲目上多实例。

六、升级与回滚

官方镜像启动命令即 ./fider migrate && ./fider，升级=换标签重启，迁移自动执行；升级前必须先备份（第三章流程）。

6.1 版本盘点与选择

docker images --format '{{.Repository}}:{{.Tag}} {{.ID}}' | grep getfider/fider

实测回显：

getfider/fider:v0.38.2 25d17db73c3d
getfider/fider:stable  eb95d0b4bf5d
getfider/fider:v0.38.1 904fde28e98a

⚠️ 实测坑（呼应部署篇镜像选型）：stable 与 v0.38.2 摘要不同，且 stable 启动横幅实测为 dev-67c52826cca176724a59dd58b9795e1bc8d67bc8——它是滚动 dev 构建，不是"最新正式版"的别名。生产升级请以 GitHub Releases 的 vX.Y.Z 标签为准，逐版钉住。

6.2 升级实测（v0.38.2 → stable，旁路库验证）

为不动主库，本次把 3.3 恢复出的旁路库 fider_restore 作为升级对象，用 stable 镜像一次性容器实测：

docker run -d --name fider-upgrade-test --network fider-v0382-stack_fider-net -p 8144:3000 \
  -e BASE_URL="http://192.168.1.172:8144" \
  -e DATABASE_URL="postgres://fider:***@db:5432/fider_restore?sslmode=disable" \
  -e JWT_SECRET="3f9c2a7e5b1d8c4a6f0e9b2c5d8a1f4e7b0c3d6a9f2e5b8c1d4a7e0f3b6c9d2" \
  -e EMAIL_NOREPLY="noreply@quzuo.net" -e EMAIL_SMTP_HOST="mailhog" -e EMAIL_SMTP_PORT="1025" \
  getfider/fider:stable
docker logs fider-upgrade-test 2>&1 | head -8

实测回显（节选）：

INFO [2026-11-01T14:13:08Z] [MIGRATE] Running migrations...
INFO [2026-11-01T14:13:08Z] [MIGRATE] Found total of 95 migration files.
INFO [2026-11-01T14:13:08Z] [MIGRATE] Current version is 202606121200
INFO [2026-11-01T14:13:08Z] [MIGRATE] Migrations are already up to date.
INFO [2026-11-01T14:13:08Z] [WEB] Application is starting
INFO [2026-11-01T14:13:08Z] [WEB] Version: dev-67c52826cca176724a59dd58b9795e1bc8d67bc8
INFO [2026-11-01T14:13:08Z] [WEB] http server started on :3000

curl -s -w "\nHTTP %{http_code}\n" http://192.168.1.172:8144/_health

实测回显：

{"status":"Healthy"}
HTTP 200

结论：v0.38.2 与 stable 迁移文件同为 95 个，migrate 幂等跳过、服务正常启动。真实跨版升级（有新增迁移）时，日志会逐条出现形如 INFO [2026-11-01T12:19:40Z] [MIGRATE] Running Version: 201701261850 (201701261850_create_tenants.up.sql) 的执行记录（首轮全新库实测见部署篇 4.3）——操作路径相同。生产主栈升级三步：

cd /opt/fider
# 1) 先备份（第三章 3.1），再改 compose 中 app 的 image 标签为新版本
docker compose pull app
docker compose up -d app
docker logs --tail 20 fider-v0.38.2-server   # 确认 http server started 与新 Version 横幅

6.3 回滚实测（旧版二进制对新版库的行为）

回滚风险点在于旧版应用面对已迁移的新 schema。实测把 v0.38.1 依次跑在升级过的旁路库上：

docker run --rm --network fider-v0382-stack_fider-net \
  -e BASE_URL="http://192.168.1.172:8144" \
  -e DATABASE_URL="postgres://fider:***@db:5432/fider_restore?sslmode=disable" \
  -e JWT_SECRET="3f9c2a7e5b1d8c4a6f0e9b2c5d8a1f4e7b0c3d6a9f2e5b8c1d4a7e0f3b6c9d2" \
  -e EMAIL_NOREPLY="noreply@quzuo.net" -e EMAIL_SMTP_HOST="mailhog" -e EMAIL_SMTP_PORT="1025" \
  --entrypoint /bin/sh getfider/fider:v0.38.1 -c "./fider migrate"

实测回显：

INFO [2026-11-01T14:14:30Z] [MIGRATE] Running migrations...
INFO [2026-11-01T14:14:30Z] [MIGRATE] Found total of 95 migration files.
INFO [2026-11-01T14:14:30Z] [MIGRATE] Current version is 202606121200
INFO [2026-11-01T14:14:30Z] [MIGRATE] Migrations are already up to date.

进一步把 v0.38.1 当完整服务启动（一次性容器挂 8148 端口）实测：

INFO [2026-11-01T14:15:41Z] [MIGRATE] Migrations are already up to date.
INFO [2026-11-01T14:15:41Z] [WEB] Version: v0.38.1-938889b52707e900cc69f497ebd124dcf7aaf5ff
INFO [2026-11-01T14:15:41Z] [WEB] http server started on :3000
{"status":"Healthy"} HTTP 200

再用部署篇初始化时保存的管理员会话 Cookie（/opt/fider/cookies.txt）向该旧版服务发业务写请求（POST /api/v1/posts），实测返回 HTTP 200——旧版对这份新库读写正常。

⚠️ 实测结论（重要）：迁移文件数相同的相邻版本之间（v0.38.1↔v0.38.2），回滚不会报错、旧版可正常读写新库——migrate 只向前不向后，schema 未被"降级"。但这不代表回滚安全：一旦跨了含新增迁移的版本（新库有旧版代码不认识的列/约束），旧版运行期 SQL 可能直接报错。因此标准回滚方案永远是：compose 改回旧镜像标签 + 用升级前的 pg_dump 恢复数据库（3.4 流程），而不是指望旧版兼容新库。

七、故障排查手册

定位顺序：先看 docker compose ps 状态列 → 再看 docker logs 的 ERROR 行 → 最后进库查 logs/migrations_history。常见症状速查：

症状	第一定位命令	已实测根因示例
app 反复重启	`docker logs fider-v0.38.2-server 2>&1 \| grep -m2 ERROR`	口令不一致 `(28P01) password authentication failed`（部署篇 11.3）
启动即退出、无日志	`docker inspect` 比对 env 完整性	缺 `JWT_SECRET`/`EMAIL_SMTP_HOST` 触发 panic（部署篇 11.2）
服务起但页面 502	`curl http://192.168.1.172:8140/_health`	端口映射被改；`/_health` 正常则查前端代理
收不到验证/登录邮件	`curl http://192.168.1.172:8142/api/v2/messages` 数邮件	SMTP 不可达时界面无任何报错，错误只留在 `[BGW]` 后台日志（见《Fider v0.38.2 故障排查与 FAQ》 4.2）
邮件链接点不开/域名不对	对照 compose 的 `BASE_URL` 与用户实际访问地址	`BASE_URL` 改动只影响此后发出的邮件，改错即全员不可达

逐项错误的现象→定位→解决实录，集中在《Fider v0.38.2 故障排查与 FAQ》，本手册不重复展开。

八、常见问题

Q1：升级需要停服多久？ docker compose up -d app 重建应用容器期间服务不可用，实测全新迁移（95 个文件）+ 启动在秒级（12:19:40 开始 migrate、同秒 http server started）；相邻版本无新迁移时更快。规划 30 秒窗口足够，谨慎起见挂维护公告。

Q2：pg_dump 需要停应用吗？ 不需要。逻辑备份对运行中的 PG 是一致的读快照；但要接受"备份时点之后"的数据在灾难恢复时丢失，故定时备份频率决定 RPO（3.2 推荐每日一次，重要变更前手动加 dump 一次）。

Q3：旁路恢复演练会拖慢主库吗？ 实测在本实例同库集群内建 fider_restore 库恢复 99 KB 转储，全程主库业务无感知（/_health 持续 200）。生产库体量大时建议恢复到独立 PG 容器，避免 IO 争抢。

Q4：metrics 的 fider_posts_total 和实际帖子数对不上？ 实测出现过指标为 0 而库内实有 1 帖（见 4.2 ⚠️），指标口径与表行数不同步，业务量统计请以 psql 为准，指标仅用于趋势告警。

Q5：能直接改 pg_data 目录里的文件做"迁移"吗？ 不能。Fider 数据一致性只靠 migrations_history 驱动的应用内迁移保证，目录级拷贝仅限同版本实例间整机搬迁（先 docker compose stop 再拷贝）。

九、参考链接

官方运维与升级文档：https://docs.fider.io/hosting-instance （Updating Fider / Configuration Reference 章节）
官方镜像标签列表：https://hub.docker.com/r/getfider/fider/tags
版本发布记录：https://github.com/getfider/fider/releases
PostgreSQL pg_dump/psql 手册：https://www.postgresql.org/docs/17/app-pgdump.html
Prometheus 抓取配置：https://prometheus.io/docs/prometheus/latest/configuration/configuration/
相关篇目：《Fider 介绍与选型指南》、《Fider v0.38.2 Docker Compose 部署指南》、《Fider v0.38.2 故障排查与 FAQ》