PieFed 1.8.10 常用 CLI 命令与工具详解

目标：以 PieFed 1.8.10 实测环境为基准，系统讲解其 CLI 体系——Flask 应用命令族（init-db / keys / reset-pwd / config_check / send-queue / daily-maintenance / spaceusage / populate_community_search / lemmy-import 等 38 个子命令）、官方维护脚本族（daily.sh / send_queue.sh / email_notifs.sh / remove_orphan_files.sh / deploy-docker2.sh / docker-dirs.sh）、supercronic 定时任务接线与数据库直查手段，全部命令给出实测回显与运维组合场景（演示账号 admin / q1w2e3r4）。

一、环境信息

PieFed：v1.8.10（Codeberg rimu/pyfedi），应用目录 /app（即仓库根），命令入口为 Flask CLI：export FLASK_APP=pyfedi.py 后执行 flask <命令>
运行时：Python 3.13 + Flask + Gunicorn 26.2.0 + Celery；数据库 PostgreSQL 17、队列/缓存 Redis 6.2
实测宿主：Ubuntu 24.04.5 LTS + Docker 29.9.2 + Compose v5.6.1，实例 127.0.0.1:8129
命令实现源码：app/cli.py（register(app) 注册全部子命令，实测 38 个）
进入应用环境执行命令的标准方式：docker exec -it piefed_app1 sh（官方 INSTALL-docker.md 口径；容器名以实际编排为准）

站内配套：《PieFed 1.8.10 介绍与选型指南》、《PieFed 1.8.10 Docker Compose 部署指南》、《PieFed 1.8.10 配置参数详解》。

二、工具概览

PieFed 的运维面 = 一套 Flask CLI + 四个 cron 包装脚本 + 两个部署脚本 + 内置 supercronic：

工具	定位	频率
`flask init-db`	建库（Site/Instance/角色/封禁表/cron 心跳）+ 交互建管理员	一次性
`flask db upgrade`	Alembic 迁移	每次升级
`flask config_check`	配置健康自检	改配置后
`flask send-queue`	消费出站联邦队列	每分钟（联邦生命线）
`flask daily-maintenance`	每日维护（排行/清理/统计）	每日
`flask email_notifs 三件套`	通知补发/退信/清理旧活动	每 6 小时
`flask remove_orphan_files`	孤儿媒体清理	每周
`daily.sh` 等四脚本	上述命令的 cron 包装	见 cron
`deploy-docker2.sh`	升级一条龙（down→pull→up --build）	升级时
supercronic（CRON=true）	应用内定时	自动

flask --help 实测全量清单（Commands 段原文照抄）：

Commands:
  admin-keys
  archive-old-posts
  clean_up_old_activities
  config_check                 Perform basic sanity checks on site...
  daily-maintenance
  daily-maintenance-celery     Schedule daily maintenance tasks via...
  db                           Perform database migrations.
  detect_vote_manipulation
  init-db
  keys
  lemmy-import                 Import data from a Lemmy database.
  limiter                      Flask-Limiter maintenance & utility commands
  migrate_community_notifs
  migrate_post_notifs
  move-files-to-s3
  move-more-post-images-to-s3
  move-post-images-to-s3
  openapi                      OpenAPI commands.
  populate_community_search
  populate_post_reply_for_api
  process_email_bounces
  publish-scheduled-posts
  remove-unnecessary-images
  remove_orphan_files          Any user-uploaded file that does not have...
  reopen
  reset-pwd
  routes                       Show the routes for the app.
  rss-feeds
  run                          Run a development server.
  send-batched-activities
  send-queue
  send_missed_notifs
  shell                        Run a shell in the app context.
  spaceusage
  testing
  translate                    Translation and localization commands.
  voting_clusters              Find groups of accounts that vote on the...

三、前置条件

应用环境内执行（docker exec -it piefed_app1 sh），且 export FLASK_APP=pyfedi.py（官方指南同口径；入口脚本已内置该导出）。
数据库/Redis 在线（多数命令带 app_context，DB 不可达直接抛栈）。
写操作命令（init-db/reset-pwd/admin-keys）会改数据，先备份 pgdata。

四、命令族详解（实测回显）

4.1 init-db：建库与管理员

两种形态（B2 排障 10.2 有自动化方案）：

flask init-db                # 官方标准：交互输入用户名/邮箱/口令（口令需 TTY）
flask init-db --interactive no   # 纯自动化：跳过建管理员

实测 --interactive no 尾部回显：

Added banned instance lemmychan.org
Manage banned instances at /admin/federation.
Initial setup is finished.

要点：前置校验 alembic 表（未迁移会提示先 flask db upgrade）与 UTF8 库编码（非 UTF8 直接拒绝并给出重建库四步指引）；落库内容含本地 Instance、Site、Admin 角色权限、29 条起步封禁域名、No-QAnon 名单与 6 项 cron 心跳记录。管理员口令规则：≥8 位、用户名不得含 @ 与空格（官方建议不要用 admin，本篇演示环境例外）。

4.2 keys / admin-keys / reset-pwd：密钥与口令

flask keys          # 生成并打印 RSA 密钥对（联邦签名用，排查 actor 签名问题）
flask admin-keys    # 重新生成并写回 user id=1（管理员密钥损坏救急）
flask reset-pwd     # 交互重置 user id=1 口令："New password for user ID 1: "

flask keys 实测输出 PEM 私钥+公钥（首行 -----BEGIN PRIVATE KEY-----）。reset-pwd 同样走 input()，非 TTY 需按 B2 10.2 方式喂入。

4.3 db：Alembic 迁移族

flask db upgrade 为启动入口自动执行（实测日志 Running upgrade 26554a31c057 -> 7c5a293ed40c, nodeinfo indexes 直至 head）；手工场景：flask db current 核对版本、flask db heads 看目标。实测 head 版本 7c5a293ed40c。

4.4 populate_community_search：社区数据集

拉 data.lemmyverse.net/community.full.json 过滤（≥50 帖且周活 ≥10、剔除封禁域名与坏名）后写 app/static/tmp/all_communities.json 与 all_sfw_communities.json，供后台"从 Lemmyverse 数据加载社区"使用；顺带拉 GitHub raw 的一次性邮箱表。出站受限时该命令会抛 httpx 超时（B2 排障 10.1 实录），它不是启动必要条件，可后补。

4.5 send-queue：联邦出站心跳

flask send-queue

实测空队列静默退出（exit 0）。源码逻辑（实测核对）：Redis 锁 lock:send-queue（timeout 300s）防并发 → 检查 Redis 内存超 REDIS_MEMORY_LIMIT 则打印 Redis memory is quite full - stopping send queue to avoid making it worse. 并置 pause_federation 暂停 600s → 随机延迟 0-10s 错峰 → 逐条投递到期活动。每分钟一次是官方 cron 模板的硬要求，漏跑表现为远程实例看不到本站活动。

4.6 config_check：配置自检

flask config_check

实测完整输出（九段制）：

PieFed Configuration Check
========================================
1. Checking required environment variables...
   ✅ SERVER_NAME is configured: 127.0.0.1:8129
   ✅ SECRET_KEY is configured
   ✅ DATABASE_URL is configured (PostgreSQL)
   ✅ MAIL_PORT is valid: 25
   ✅ DB_POOL_SIZE is valid: 10
   ✅ DB_MAX_OVERFLOW is valid: 30
   ✅ CACHE_REDIS_URL format is valid
   ✅ CELERY_BROKER_URL format is valid
2. Checking database connection...
   ✅ Database connection successful
3. Checking Redis connection...
   ✅ Redis connection successful
4. Checking directory write permissions...
   ✅ app/static/tmp is writable
   ✅ app/static/media is writable
   ✅ logs is writable
6. Checking cache configuration...
   ✅ Cache type: RedisCache
7. Checking S3 configuration...
   ℹ️  S3 not configured (local file storage will be used)
8. Checking ActivityPub configuration...
   ✅ Admin user configured
9. Checking database migration system...
   ✅ Database migration system is initialized
========================================
CONFIGURATION CHECK SUMMARY
========================================
⚠️  2 warning(s) found:
   ⚠️  Mail server not configured - email functionality will be disabled
   ⚠️  SERVER_NAME not properly configured for federation
⚠️  Configuration has warnings but should work.

官方口径：✅ 通过、⚠️ 可容忍、❌ 必须修复。

4.7 daily-maintenance：每日维护

flask daily-maintenance

实测回显尾部（逐项任务编号 + 完成时间戳）：

21 2026-11-02 08:47:26.656166
22 2026-11-02 08:47:26.656276
Finished 2026-11-02 08:47:26.658107

一次跑完帖子热度/排行重算、过期投票清理、实例统计等任务；daily-maintenance-celery 是其投递 Celery 的异步版（大实例避免阻塞 cron 窗口）。

4.8 spaceusage / remove_orphan_files：存储治理

flask spaceusage

实测：新实例无用户文件时无输出属正常——源码仅对 filesize>0 且 num_content>0 的用户打印 CSV 行 id,"ap_id",filesize,num_content。

flask remove_orphan_files

扫 app/static/media/users 下无 File 表记录的文件直接删除，并写 cron 心跳（log_cron_task_to_db）。静默完成即成功。

4.9 lemmy-import：从 Lemmy 迁移

flask lemmy-import
# 交互输入源库连接串，实测校验提示：
# Connection should be something like "postgresql://lemmy:eeeee@127.0.0.1:5434/lemmy"

直连 Lemmy PostgreSQL 库导入用户/社区/帖子（要求 postgresql:// 前缀，先 SELECT 1 探活）。跨软件迁移主通道，大库建议停写执行。

4.10 治理分析族：voting_clusters / detect_vote_manipulation

flask detect_vote_manipulation：按投票配额与行为特征圈出操纵嫌疑账号。
flask voting_clusters：源码用泊松尾概率 + 极大团算法找协同投票簇（poisson_tail_log10/maximal_cliques），输出供 /admin 处置。治理类命令只读不改数据，可放心试跑。

4.11 其余命令速览

命令	用途
`send_missed_notifs` / `process_email_bounces` / `clean_up_old_activities`	邮件通知补发 / 退信处理 / 旧活动清理（email_notifs.sh 三连）
`publish-scheduled-posts`	定时帖发布（配合 API 排期）
`archive-old-posts`	执行 `ARCHIVE_POSTS` 归档
`rss-feeds`	拉取社区订阅的 RSS 源发帖（需 `RSS_FEEDS=1`）
`move-files-to-s3` / `move-post-images-to-s3` / `move-more-post-images-to-s3`	存量媒体分批迁 S3（配 C1 4.6 节开关）
`migrate_community_notifs` / `migrate_post_notifs` / `populate_post_reply_for_api`	通知与 API 索引的旧数据回填
`reopen`	重开实例（维护模式后恢复）
`remove-unnecessary-images`	清理冗余中图（官方注释警告 2025-06 起移动端需要中图，勿随手跑）
`translate init/update/compile <lang>`	pybabel 翻译工作流（新增语言包）
`shell` / `routes` / `openapi` / `limiter` / `testing`	Flask 内置：应用上下文 REPL（B2 10.2 建号即用）、路由表、API 文档生成、限流维护、测试夹具

五、官方维护脚本族

四个 cron 包装脚本内容实测（均为 source venv/bin/activate + flask <命令> 两行式；应用环境内 activate 失败静默跳过、PATH 已含解释器，不影响执行）：

# daily.sh        → flask daily-maintenance
# send_queue.sh   → flask send-queue
# email_notifs.sh → flask send_missed_notifs && flask process_email_bounces && flask clean_up_old_activities
# remove_orphan_files.sh → flask remove_orphan_files

接线二选一（B2 第八节）：compose 加 CRON=true 启用内置 supercronic（docker.cron 实测四条：每日 02:05 daily、每分钟 send_queue、每 30 分 email_notifs、周一 04:05 orphan），或宿主 crontab 调 docker exec piefed_app1 bash -c "cd /app && ./xxx.sh"。

部署脚本：

./docker-dirs.sh      # 建 pgdata/media/logs/tmp 并授权（B2 4.4，root 需补 chown 1000）
./deploy-docker2.sh   # 升级：DOCKER_BUILDKIT=1 → compose down → git pull → compose up -d --build

六、数据库与队列直查手段

运维排障常需绕过应用直查（实测可用）：

# 业务数据（db 服务内置 postgresql-client）
docker exec piefed-v1810-stack-db-1 psql -U piefed -d piefed -c "select name,post_count from community,post where post.community_id=community.id;"
  name   | post_count
---------+------------
 techops |          1

docker exec piefed-v1810-stack-db-1 psql -U piefed -d piefed -c "select count(*) from send_queue;"   # 出站积压
docker exec piefed-v1810-stack-db-1 psql -U piefed -d piefed -c "select version_num from alembic_version;"  # 迁移位

# 队列与联邦状态
docker exec piefed-v1810-stack-redis-1 redis-cli -n 1 llen celery          # Celery 积压
docker exec piefed-v1810-stack-redis-1 redis-cli get pause_federation      # 联邦暂停位（1=暂停中）

# Celery 健康（compose 内置 healthcheck 同款）
docker exec piefed_celery1 celery -A celery_worker_docker.celery inspect ping

# 联邦元数据
curl -s http://127.0.0.1:8129/nodeinfo/2.0.json

七、运维组合场景速查

场景	命令序列
升级版本	`git checkout v1.8.11`（示例）→ `./deploy-docker2.sh` → `flask config_check`
忘记密码	`flask reset-pwd`（TTY）→ 登录验证
联邦停摆排查	`redis-cli get pause_federation` → `psql -c "select count(*) from send_queue"` → 手动 `flask send-queue` 观察输出 → 检查 cron 心跳表
换域名	官方口径不可行（SERVER_NAME 变更=清库重来，见 B2 第三节）
迁对象存储	配 S3 变量 → `flask move-files-to-s3` → `move-post-images-to-s3` → `move-more-post-images-to-s3` 分批
从 Lemmy 搬家	停写 → `flask lemmy-import` 按提示连源库 → `flask populate_community_search` → `flask daily-maintenance`
治理巡查	`flask voting_clusters` → `flask detect_vote_manipulation` → 面板处置

八、注意事项与 FAQ

所有 flask 命令都在应用目录/环境内执行，宿主直接跑会缺依赖；官方口径 docker exec -it piefed_app1 sh 进入后执行。
口令类交互依赖 TTY（init-db 的 pwinput、reset-pwd 的 input），CI/管道场景见 B2 10.2 两条实测方案。
send-queue 的随机 0-10s 延迟是设计行为（全网实例同分钟起跑的错峰保护），脚本超时设置别小于 30s。
remove-unnecessary-images 不要跑：源码注释明确 2025-06 起链接帖也需要中图，官方保留命令仅为历史兼容。
cron 心跳有后台告警：init-db 写入的 6 项心跳（CronJobLog）超时未更新会在 /admin 提示"维护任务没在跑"，比翻日志直观。
celery 队列分工：celery,background,send 三队列（入口脚本 --queues 实测），只起 web 不起 celery 会导致图片处理与后台任务堆积。

九、参考链接

命令源码：app/cli.py、daily.sh、send_queue.sh、email_notifs.sh、remove_orphan_files.sh、deploy-docker2.sh、docker.cron（https://codeberg.org/rimu/pyfedi ，v1.8.10）
官方安装与运维指引：INSTALL-docker.md / INSTALL.md
治理功能说明：https://join.piefed.social/2024-06-22/piefed-features-for-growing-healthy-communities/
站内配套：《PieFed 1.8.10 Docker Compose 部署指南》、《PieFed 1.8.10 配置参数详解》、《Lemmy 0.19.21 常用 CLI 命令详解》