qpixel 0.13.0 常用 CLI 命令与工具详解

目标：把 qpixel v0.13.0 实例上可脚本化的全部命令行入口——rails/rake 主命令、18 个运维脚本（scripts/）、13 个数据修复脚本（db/scripts/）、whenever 定时任务定义、maintenance 任务体系与 MySQL 直查——逐条实测并留存回显。本文命令与输出均为 2026-11-02 实测。

一、环境信息

软件版本：qpixel v0.13.0（GitHub Release 2026-09-12，2026-11-02 查询）
应用根：/code（rails about 实测）；部署方式见《qpixel 0.13.0 Docker Compose 部署指南》
数据库：MySQL 8.4.2，当前环境库 qpixel_dev，schema 版本 20260614135514（rake db:version 实测）
演示账号：admin / q1w2e3r4（全局管理员）；社区 Dev Community
命令入口说明：本文实验环境应用跑在编排服务单元内，等价入口为 docker compose exec -T uwsgi <命令>（下文回显原样照抄）；正文命令一律按应用根直接执行的形式书写。

二、工具概览

入口	位置	用途	调用方式
`rails`	应用根 PATH（`bin/rails` 同体）	主命令：server/console/runner/routes/db:* 等	`rails <命令>`
`rake`	应用根 PATH（`bin/rake`）	任务器：`rake -T` 实测 47 项，与 rails db:* 重叠	`rake <任务>`
运维脚本	`scripts/`（18 项）	缓存清理、声望重算、邮件推送、备份、清库等	`rails r scripts/<x>.rb`
定时任务定义	`config/schedule.rb`	whenever 语法的 13 条周期 runner 作业	`whenever --update-crontab`（生产侧）
数据修复脚本	`db/scripts/`（13 项）	视图重建、分数/计数/声望重算、去重 SQL	`.rb` 用 `rails r`，`.sql` 走 mysql 客户端
maintenance 任务	`app/tasks/maintenance/`（2 个任务类）	批量数据修正，网页 `/maintenance` 排队执行	Web UI（gem Engine 挂载，实测路由）
MySQL 客户端	数据库层	直查表/视图、执行 `.sql` 脚本	`mysql -uqpixel -p <库名>`
导入工具	`scripts/import/`	api/database/dump/stack 四种导入	`rails r scripts/import/<x>.rb`

三、前置条件

$ rails -v; ruby -v; bundle -v; rake --version
Rails 8.1.3.1
ruby 3.4.5 (2025-07-16 revision 20cda200d3) +PRISM [x86_64-linux]
Bundler version 2.7.2
rake, version 13.4.2

噪音提示（重要）：每次执行 rails/rake 都会先刷固定噪音两则——To use retry middleware with Faraday v2.0+, install 'faraday-retry' gem 与两遍 fatal: not a git repository ...（源码为归档包解出无 git 目录，config/initializers/zz_cache_setup.rb 调 git rev-parse 取版本信息所致）。下文回显均已剔除这些行，属正常非错误。

四、各工具详解

4.1 rails 主命令

rails -h 实测输出（头部）：

Usage:
  bin/rails COMMAND [options]

You must specify a command. The most common commands are:

  generate     Generate new code (short-cut alias: "g")
  console      Start the Rails console (short-cut alias: "c")
  server       Start the Rails server (short-cut alias: "s")
  test         Run tests except system tests (short-cut alias: "t")
  test:system  Run system tests
  dbconsole    Start a console for the database specified in config/database.yml
               (short-cut alias: "db")
  plugin new   Create a new Rails railtie or engine

All commands can be run with -h (or --help) for more information.

其后按字母序列出全部 80+ 任务（db:create…zeitwerk:check），与 4.2 的 rake 任务目录基本重合，此处不重复。

rails about（环境与版本巡检，实测全文）：

About your application's environment
Rails version             8.1.3.1
Ruby version              ruby 3.4.5 (2025-07-16 revision 20cda200d3) +PRISM [x86_64-linux]
RubyGems version          3.6.9
Rack version              2.2.23
JavaScript Runtime        Node.js (V8)
Middleware                Rack::MiniProfiler, ActionDispatch::HostAuthorization, Rack::Sendfile, ActionDispatch::Static, ActionDispatch::Executor, RailsPerformance::Rails::MiddlewareTraceStorerAndCleanup, RailsPerformance::Rails::Middleware, ActionDispatch::ServerTiming, ActiveSupport::Cache::Strategy::LocalCache::Middleware, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, ActionDispatch::RemoteIp, Sprockets::Rails::QuietAssets, Rails::Rack::Logger, ActionDispatch::ShowExceptions, WebConsole::Middleware, ActionDispatch::DebugExceptions, ActionDispatch::ActionableExceptions, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ContentSecurityPolicy::Middleware, Rack::Head, Rack::ConditionalGet, Rack::ETag, Rack::TempfileReaper, Warden::Manager
Application root          /code
Environment               development
Database adapter          mysql2
Database schema version   20260614135514

rails runner（数据层操作主力，官方 README 推荐入口）。实测示例：

$ rails runner 'puts Community.first.name'
Dev Community
$ rails runner 'u = User.find_by(username: "admin"); puts "admin user: id=#{u.id} global_admin=#{u.is_global_admin} email=#{u.email}"'
admin user: id=1 global_admin=true email=admin@example.com
$ rails runner 'RequestContext.community = Community.first; %w[SiteName FreeVotes NewUserInitialRep MathJaxEnabled].each { |n| puts "#{n} = #{SiteSetting[n].inspect}" }'
SiteName = "QPixel"
FreeVotes = 5
NewUserInitialRep = 1
MathJaxEnabled = false

注意数据库相关操作先 RequestContext.community = Community.first 把上下文钉到目标社区（官方 README 第 9 步与配置篇 Q2 同源）。

rails console（交互 REPL）：rails c 进入；同样先设 RequestContext.community。rails dbconsole 直接进 MySQL 客户端（按 database.yml 连接）。

rails server：部署编排的启动脚本已自动执行 rails server -b 0.0.0.0（实测监听 http://0.0.0.0:3000，=> Booting Puma）；官方 README 说明若用 Dockerfile.dev 构建配置则需手动执行本命令起服务。

rails routes（路由巡检，实测节选）：

Routes for application:
                                  Prefix Verb     URI Pattern                                                                                       Controller#Action
                        new_user_session GET      /users/sign_in(.:format)                                                                          users/sessions#new
                            user_session POST     /users/sign_in(.:format)                                                                          users/sessions#create
                    destroy_user_session DELETE   /users/sign_out(.:format)                                                                         users/sessions#destroy
                       new_user_password GET      /users/password/new(.:format)                                                                     devise/passwords#new

管理入口路由实测：/admin/settings（site_settings#index）、/admin/settings/global、/maintenance（MaintenanceTasks::Engine 挂载）。

rails secret（生成凭据密钥，实测）：

$ rails secret
db17e6ea029ee5dcd11b9cb090162cddb20053867bd060ea939c6801124c83b0041da344b1f6c077d60c6a735b93a34f4b1c309bdee8ef33cba36046025ef789

rails db: 系列*（实测）：

$ rails db:version
database: qpixel_dev
Current version: 20260614135514

$ rake db:migrate:status | tail -4
   up     20260513185013  Add link to dumps
   up     20260519211432  Add checksum to dumps
   up     20260520112652  Add filter default name
   up     20260614135514  Actually remove trust level from users

rake -T 实测标准 db 系列全部可用：db:create / db:drop / db:migrate / db:migrate:status / db:migrate:redo / db:prepare / db:reset / db:rollback / db:schema:load / db:seed / db:setup / db:version 等。rails db:seed 幂等（实测二次执行输出 SiteSetting: skipped 112 类跳过行）。

rails test：官方 README 给出 rails test（非系统测试）、rails test:system（需浏览器，Dockerfile.dev 内置 Firefox）、rails test:all 三种跑法；本文未跑全量测试，不作回显承诺。

4.2 rake 任务目录（rake -T 实测 47 项）

与运维直接相关的分组（按实测 47 项归组）：

组	任务
db:*	create、drop、migrate（含 up/down/redo/status）、prepare、reset、rollback、schema:dump/load、schema:cache:dump/clear、seed、seed:replant、setup、version、environment:set、fixtures:load、encryption:init、system:change
assets	`assets:precompile`（生产发布必跑）、`assets:clean[keep]`、`assets:clobber`、`assets:environment`
日志/临时	`log:clear`（可 `LOGS=test,development` 指定）、`tmp:clear`、`tmp:create`
测试	`test`、`test:db`
安装类	`action_mailbox:install(:migrations)`、`action_text:install(:migrations)`、`active_storage:install`、`maintenance_tasks:install:migrations`
杂项	`app:template`、`cache_digests:*`、`time:zones[...]`、`yarn:install`、`zeitwerk:check`

4.3 scripts/ 运维脚本（18 项实测清单）

调用形态统一为 rails r scripts/<脚本>.rb（rails runner 上下文，非裸 ruby）。清单（ls scripts/ 实测）：

脚本	用途
`clear_cache.rb`	清 `network/` 缓存键与 `pinned_links` Redis 键
`recalc_abilities.rb`	重算全体用户 abilities/privileges（`RecalcAbilitiesJob.perform_now`），支持 `-v/--verbose`、`-q/--quiet`
`run_user_stats.rb`	用户统计作业
`run_spam_cleanup.rb`	spam 清理作业
`cleanup_drafts.rb` / `cleanup_votes.rb`	草稿/投票清理
`run_complaints_closure.rb`	投诉结案作业
`run_thread_followers_cleanup.rb` / `run_new_thread_followers_cleanup.rb`	主题关注关系去重清理
`send_subscription_emails.rb`	订阅邮件推送
`run_summary_mailer.rb`	摘要邮件推送
`mail_uncaptured_donations.rb`	未入账捐赠补发邮件
`prune_email_logs.rb`	邮件日志裁剪
`data_dump.rb`	数据导出（`DataDumpJob.perform_now`）
`database_backup.rb`	数据库备份（`DatabaseBackupJob.perform_now`，落 `AppConfig.server_settings['db_backups_path']`）
`create_initial_tags.rb`	初始标签创建
`wipe_everything.rb`	危险：清空全部业务表并重建种子（见下）
`import/`	`api_import.rb`、`database_import.rb`、`dump_import.rb`、`stack_import.rb` 四种导入

实测执行两例：

$ rails r scripts/clear_cache.rb
$ echo $?
0
$ rails r scripts/recalc_abilities.rb -q
$ echo $?
0

（quiet 模式成功无输出；-v 会逐用户打日志。）

wipe_everything.rb 源码实测要点：非 development 环境直接拒绝——

unless Rails.env.development?
  puts "You're on production. Don't be dumb."
  exit 255
end

随后关外键、逐表 DELETE + 重置自增（保留 ar_internal_metadata、schema_migrations），重建 Dev Community、清缓存、重跑种子。生产误跑会毁数据，本文未执行。

4.4 config/schedule.rb 定时任务（whenever 语法，实测全文归纳）

13 条周期作业全部是 runner 'scripts/<x>.rb' 形态（时刻为应用进程时区）：

every 1.day  02:00  send_subscription_emails.rb     every 7.days 02:35 run_thread_followers_cleanup.rb
every 1.day  02:05  mail_uncaptured_donations.rb    every 7.days 02:40 run_new_thread_followers_cleanup.rb
every 1.day  02:10  prune_email_logs.rb             every 7.days 05:00 run_user_stats.rb
every 1.day  02:15  run_spam_cleanup.rb             every 7.days 04:00 data_dump.rb
every 1.day  02:20  cleanup_drafts.rb               every 6.hours      recalc_abilities.rb
every 1.day  02:25  cleanup_votes.rb                every 30.minutes   run_summary_mailer.rb
every 1.day  02:30  run_complaints_closure.rb

另有被注释的备份作业模板（# every 1.day, at: '16:00' do runner 'scripts/database_backup.rb'），启用即接入上表。生产托管方式：whenever --update-crontab 生成交给 crontab（whenever gem 在 Gemfile 中，本实验环境未装 crontab 托管，未实测）。

4.5 db/scripts/ 数据修复脚本（13 项实测清单）

ls db/scripts/：create_tags_path_view.rb、create_tags_path_view.sql、dump_permitted_columns.yml、posts_with_duplicate_new_thread_followers.sql、potential_spam_profiles.sql、recalc_post_scores.sql、remove_exact_duplicates.sql、rep_recalc_community.sql、rep_recalc_user.sql、reset_answer_counts.sql、reset_collations.rb、reset_thread_reply_counts.sql、tag_children.sql、threads_with_duplicate_followers.sql。

.rb 走 rails runner、.sql 走 MySQL 客户端。两例实测：

视图重建（entrypoint 建库流程同款）：

$ rails r db/scripts/create_tags_path_view.rb
$ echo $?
0
# 脚本仅一行：ActiveRecord::Base.connection.execute File.read(Rails.root.join('db/scripts/create_tags_path_view.sql'))
# 成功无输出；验证视图存在：
$ mysql -uqpixel -pqpixel qpixel_dev -e "SHOW FULL TABLES WHERE Table_type='VIEW'"
Tables_in_qpixel_dev      Table_type
tags_paths                VIEW

（mysql 客户端会提示 Using a password on the command line interface can be insecure.，属标准告警。）

帖子分数重算（纯 SQL 脚本经客户端执行）：

$ mysql -uqpixel -pqpixel qpixel_dev < /tmp/recalc.sql   # 即 db/scripts/recalc_post_scores.sql
$ echo $?
0

其余脚本按名取义：rep_recalc_user.sql/rep_recalc_community.sql（声望重算，逐用户/逐社区）、reset_answer_counts.sql/reset_thread_reply_counts.sql（回答数/回复数重置）、remove_exact_duplicates.sql/tag_children.sql（去重与标签层级）、potential_spam_profiles.sql（疑似 spam 画像查询）、reset_collations.rb（批量改排序规则）。

4.6 maintenance 任务体系

app/tasks/maintenance/ 实测两个任务类（maintenance_tasks gem）：

FixRejectedEditStatesTask：collection 取 SuggestedEdit.rejected，逐条比对帖子历史修正被拒编辑的状态字段；
InitializeUserWebsitesTask：批量初始化用户站点信息。

入口是 Web 而非 rake：gem Engine 挂载在 /maintenance（routes.rb 实测 mount MaintenanceTasks::Engine, at: '/maintenance'），initializer 配 MaintenanceTasks.parent_controller = 'TasksController'（沿用站内任务权限模型）。管理员登录后排队执行；rake -T 里只有 maintenance_tasks:install:migrations 一项安装辅助任务，无运行入口。

4.7 数据库直查（MySQL 客户端）

连接参数实测自 config/database.yml：host db、port 3306、用户/口令 qpixel/qpixel，三环境库 qpixel_dev/qpixel_test/qpixel。rails dbconsole 是同款连接的快捷入口。常用巡检：

mysql -uqpixel -pqpixel qpixel_dev -e "SHOW FULL TABLES WHERE Table_type='VIEW'"   # 实测见 4.5
mysql -uqpixel -pqpixel qpixel_dev -e "SELECT COUNT(*) FROM site_settings"          # 112（配置篇实测）

五、注意事项

噪音行勿当错误：faraday-retry 提示与 fatal: not a git repository 每次必现（成因见第三章），脚本里做结果判定请以 exit code 为准。
runner 上下文：rails r/rails runner 内做数据操作前先 RequestContext.community = Community.first（或目标社区），否则 SiteSetting 等按错误社区作用域读写。
脚本一律 rails r 执行：scripts/ 与 db/scripts/*.rb 依赖 Rails/ActiveRecord 上下文，裸 ruby 会崩。
wipe_everything.rb 有 production 护栏但仍是毁库脚本：dev 环境执行即清空全部业务表（4.3 节源码实测）。
升级版本后：跑 rails db:migrate（entrypoint 首建流程同款），必要时补 rails r db/scripts/create_tags_path_view.rb 与 rails db:seed。
Spring 预加载器：官方 README 的 runner 回显带 Running via Spring preloader in process 111（bin/spring 实测存在）；本文编排环境回显无此行，说明未走 Spring，两种形态输出等价。
邮件类脚本（send_subscription_emails/run_summary_mailer 等）在 development 环境发信走 letter_opener_web 拦截，浏览器开 /letter_opener 查看（实测 HTTP 200），不会真发。

六、常见问题

Q1：bin/rails 和 rails 选哪个？ A：同一入口（rails -h 用法行即 bin/rails COMMAND）。应用根 PATH 已装好 binstub，两种写法回显一致。

Q2：rails r scripts/xxx.rb 报 undefined local variable or method？ A：该脚本需要 Rails 上下文，确认用的是 rails r（runner）而非 ruby；带 OptionParser 的脚本（如 recalc_abilities.rb）参数要放在脚本名之后：rails r scripts/recalc_abilities.rb -q（实测）。

Q3：db/scripts/*.sql 能用 rails r 跑吗？ A：不能，.sql 是纯 SQL，走 MySQL 客户端重定向（4.5 节实测 recalc_post_scores.sql exit=0）；.rb 才用 rails r。

Q4：想跑定时任务但没装 cron？ A：单条手动补跑即可：rails r scripts/<x>.rb（4.3 表全量脚本均可手动执行）；周期化再上 whenever --update-crontab。

Q5：maintenance 任务在 rake -T 里找不到？ A：设计如此——该 gem 的运行入口在 Web（/maintenance），rake 只有安装迁移任务（4.6 节实测）。

Q6：每次命令都刷 fatal: not a git repository，能消掉吗？ A：在应用根放一个真实 git 目录（clone 而非 tar 包）即消失；或无视——zz_cache_setup.rb 拿不到 commit 信息只影响版本展示缓存，不影响功能。

七、参考链接

qpixel 仓库：https://github.com/codidact/qpixel
官方 Docker 说明（第 9 步 runner/console 用法）：https://github.com/codidact/qpixel/blob/develop/docker/README.md
Rails 官方测试指南（The Rails Test Runner）：https://guides.rubyonrails.org/testing.html#the-rails-test-runner
maintenance_tasks gem：https://github.com/shopify/maintenance_tasks
站内互链：《qpixel 介绍与选型指南》、《qpixel 0.13.0 Docker Compose 部署指南》、《qpixel 0.13.0 配置参数详解》