qpixel 0.13.0 配置参数详解

目标：把 qpixel v0.13.0 的四层配置体系（数据库层 SiteSetting 112 项、文件层 AppConfig 四份 YAML、连接层 database/storage/cable、环境变量层 ENV）的参数全量摸清、逐项实测，并给出生产配置模板。本文全部数值与回显均为 2026-11-02 在已跑通的 v0.13.0 实例上实测。

一、环境信息

• 软件版本：qpixel v0.13.0（GitHub Release 2026-09-12，2026-11-02 查询）
• 应用根：/code（rails about 实测 Application root /code）
• 运行栈实测回显（rails about，2026-11-02）：

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)
Application root          /code
Environment               development
Database adapter          mysql2
Database schema version   20260614135514

• 数据库：MySQL 8.4.2，当前环境库 qpixel_dev；Redis 作缓存/队列
• 社区数据：单社区 Dev Community（id=1）；演示账号 admin / q1w2e3r4（全局管理员）
• 配置体系四层（源码实测归纳）：

• 命令入口说明：本文实验环境应用跑在编排服务单元内，等价入口为 docker compose exec -T uwsgi <命令>（下文回显均原样照抄）；正文命令一律按应用根直接执行的形式书写。

二、前置条件

• 已按《qpixel 0.13.0 Docker Compose 部署指南》完成部署并通过验证。
• 工具版本实测：

$ 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+... 与两遍 fatal: not a git repository（源码为归档包解出、无 git 目录，config/initializers/zz_cache_setup.rb 调 git rev-parse 所致），属固定噪音，下文回显不再重复。

三、参数查看与修改方式

3.1 数据库层：SiteSetting

管理后台 UI（routes.rb 实测路由）：

命令行读写（app/models/site_setting.rb 定义的 [] / []= API）。实测写改还原（rails runner）：

SiteSetting['SiteName']                      # => "QPixel"
SiteSetting['SiteName'] = 'Dev Community Renamed'
SiteSetting['SiteName']                      # => "Dev Community Renamed"
SiteSetting['SiteName'] = 'QPixel'           # 还原
# => restored: "QPixel"

读取语义（模型源码实测）：

• SiteSetting[name, community: nil] 走 Rails.cache，键形如 SiteSettings/<community_id>/<Name>；
• 落库查询 applied_setting：先取本社区行（for_community_id），再回退全局行（community_id IS NULL，priority_order 排后）——社区级覆盖全局级；
• 按行上的 value_type 经 SettingConverter 转型后返回（boolean/integer/float/string/text/array/uri_path 七种，模型源码 [:array, :boolean, :float, :integer, :string, :text, :uri_path].each 定义谓词方法）；
• 键名大小写敏感：实测 SiteSetting['site_name'] 返回 nil，SiteSetting['SiteName'] 才命中。

全局/社区分布实测：

$ rails runner 'puts "global=#{SiteSetting.where(community_id: nil).count} scoped=#{SiteSetting.where.not(community_id: nil).count}"'
global=26 scoped=86

即 112 项中 26 项全局（多社区共享默认），86 项按社区各存一行。

3.2 文件层：AppConfig

加载机制（config/initializers/config.rb 全文实测）：

require 'ostruct'

AppConfig ||= OpenStruct.new

Dir.glob(Rails.root.join('config/config/*.yml')).each do |f|
  basename = Pathname.new(f).relative_path_from(Pathname.new(Rails.root.join('config/config'))).to_s
  root_key = basename.gsub('.yml', '')
  processed = ERB.new(File.read(f)).result(binding)
  AppConfig[root_key] = YAML.load(processed, aliases: true)
end

要点：config/config/ 下每份 YAML 以文件名成为 AppConfig 的一个根键（server_settings、preferences、spam_protection、safety_center），内容先过 ERB 再 YAML 解析；启动时一次性加载，改文件必须重启应用生效。

读取实测：

$ rails runner 'puts AppConfig.server_settings.to_h.inspect'
[["registration_rate_limit", 3600], ["user_sudo_duration", 30], ["network_base_domain", "codidact.com"], ["db_backups_path", "/var/sql-backups"]]

修改方式：直接编辑对应 config/config/<root_key>.yml，重启应用。

3.3 连接层

config/database.yml（MySQL/Redis 连接，全文见部署篇第八章）、config/storage.yml（上传存储后端）、config/cable.yml（ActionCable，REDIS_URL 默认 redis://localhost:6379/1）、config/puma.rb（线程/端口/PIDFILE）。均为启动时读取。

3.4 环境变量层

两层注入链（编排文件实测）：.env 只做 compose 插值（端口、社区名、环境名等进编排定义）；docker/env 经 env_file 注入进程。uwsgi 进程 env 实测注入清单：

COMMUNITY_ADMIN_EMAIL=admin@example.com
COMMUNITY_ADMIN_PASSWORD=q1w2e3r4
COMMUNITY_ADMIN_USERNAME=admin
COMMUNITY_NAME=Dev Community
CONFIRMABLE_ALLOWED_ACCESS_DAYS=2
LOCAL_DEV_PORT=8131
MAILER_PROTOCOL=https
RAILS_ENV=development

REDIS_URL、PORT、RAILS_MAX_THREADS、WEB_CONCURRENCY 等未注入，走代码默认值（见 5.14 节）。

四、参数总览

4.1 SiteSetting 分类与数量（rails runner 实测 GROUP BY category）

AdvancedSettings         6
Display                  12
Email                    19
HelpAndGuidance          4
Integrations             9
RateLimits               14
ReputationAndVoting      4
SafetyCenter             3
SignInAndSignUp          4
SiteDetails              26
Tour                     10
Widgets                  1

合计 112 项。表列（schema.rb 实测）：category、community_id、name、value、value_type、options、description、created_at、updated_at；name 在 (community_id, name) 范围内唯一（模型 validates，大小写不敏感）。

4.2 SiteSetting 全量清单（category | name | value_type，实测导出）

（Email 分类实测存在同名重复行：NoReplySenderEmail/NoReplySenderName 各出现两次，系不同社区各存一行所致，非表异常。）

4.3 AppConfig 文件层清单

五、核心参数分类详解

5.1 SiteDetails：站点与网络身份（26 项）

种子初始化后本社区前 5 行实测：

SiteName = QPixel [string] community=1
SiteLogoPath = /assets/logo.png [string] community=1
MobileLogoPath =  [string] community=1
SiteCategoryHeaderDefaultColor = blue [string] community=1
SiteHeaderIsDark = f [boolean] community=1

• SiteName/SiteLogoPath/MobileLogoPath/IconPath：站名与 logo（浏览器标题实测渲染为 [DEV] Q&A - QPixel，[DEV] 前缀即当前社区名）。
• NetworkName/NetworkURL/NetworkMascotName/NetworkMascotLogoPath/Widgets.NetworkPitch：多社区「网络」品牌，跨社区导航处展示。
• ContentLicenseName/ContentLicenseLink：社区内容许可（qpixel 特色：许可逐帖可选，见 A1）。
• RestrictedAccess + RestrictedAccessFrontPageText + RestrictedAccessHelpPagesPublic + RestrictedAccessPolicyPagesPublic：受限访问模式四件套，开启后未登录仅见首页文案与白名单页。
• MaxTitleLength/MaxThreadTitleLength/MaxTagLength/MaxEditCommentLength/MaxFlagReasonLength：输入长度闸门；AllowedUploadTypes（array）：上传 MIME 白名单。
• CSSPath/JSPath（uri_path 类型）：社区级自定义样式/脚本注入路径。
• AdministratorContactEmail：管理员对外邮箱。

5.2 ReputationAndVoting：声望与投票（4 项）

实测值（先 RequestContext.community = Community.first 再读）：

SiteName = "QPixel"
FreeVotes = 5
NewUserInitialRep = 1
MathJaxEnabled = false

• NewUserInitialRep=1：新用户初始声望；FreeVotes=5：声望不足者每帖可用投票数上限；
• AllowSelfVotes（boolean）：是否允许自投票；NewSiteMode（boolean）：新站模式，声望阈值随帖子数动态衰减（配合 AdvancedSettings.ScoringVariable、LotteryAgeDeprecationSpeed）。

5.3 RateLimits：频控（14 项）

命名规律 RL_<动作> 与 RL_NewUser<动作> 双轨：动作覆盖 Comments / CommentsOwnPosts / TopLevelPosts / SecondLevelPosts / SuggestedEdits / Votes / Flags。普通用户与新用户各一档，整数值为「每单位时间允许次数」。新装站最常被调的是 RL_NewUser* 组（默认偏紧，防 spam 但卡住活跃新用户）。

5.4 Display：展示与排版（12 项）

MathJaxEnabled（实测 false）、SyntaxHighlightingEnabled：公式/代码高亮开关；HotQuestionsCount、HotPostsScoreThreshold（AdvancedSettings）：热帖窗口大小与入榜分数阈值；TableOfContentsThreshold/TableOfContentsExcerptLength：帖子目录生成条件；AdminBadgeCharacter/ModBadgeCharacter/UserCardDetails：徽章与名片；SidebarNoticeText：侧栏公告；PostBodyListTruncateLength：列表页摘要截断；VoteSummaryAutoExpandLastNrOfDays：投票摘要默认展开天数。

5.5 Email：发信人矩阵（19 项）

按邮件用途分组的 Sender/ReplyTo/Receiver 三元组：AllUsers*（全员邮件）、NoReply*（系统通知）、Subscription*（关注推送）、ModeratorDistributionList*（版主通报）、Donation* + DonationSupport* + Support*（捐赠/支持）、FriendlyEmailFooter（统一页脚）、InterestingSubscriptionScoreThreshold（interesting 订阅的分数门槛）。生产必改全部 *SenderEmail，否则默认值直发即被拒。

5.6 AdvancedSettings：引擎参数（6 项）

MaxRequestBodySize（integer，请求体上限）、ScoringVariable（integer，计分窗口参数）、LotteryAgeDeprecationSpeed（float，热帖彩票衰减）、HotPostsScoreThreshold（float）、EnableMandatoryGlobalAdminMod2FA（boolean，全局管理员强制 2FA）、SoftDeleteTransferUser（integer，软删帖归属转移目标用户 id）。

5.7 SignInAndSignUp / SafetyCenter / Integrations / HelpAndGuidance / Tour

• SsoSignIn/MixedSignIn/Enable2FAForSsoUsers/AllowSsoDisconnect：Codidact SSO 登录三态与解绑开关；
• OSADirector（integer，用户 id）/OSATrainingEnabled/ContentPolicyURL：安全中心（举报处理）责任人与培训开关；
• AnalyticsURL/AnalyticsSiteId：Matomo 类统计接入；SEApiClientId/SEApiClientSecret/SEApiKey：Stack Exchange 内容导入凭据；AllowContentTransfer、DonationsEnabled/LoadStripeEverywhere（Stripe 捐赠）、ChatLink；
• HelpAndGuidance 4 项 + Tour 10 项：提问/回答指引文案与新手导览各步说明，全 text 型，纯内容配置。

5.8 全局 vs 社区级

实测 global=26 / scoped=86。全局行 community_id IS NULL，在 /admin/settings/global 维护；社区行覆盖全局行（applied_setting 的 priority_order 逻辑）。多社区运营时，品牌类（SiteName、Logo、许可）逐社区设，网络类（NetworkName、SSO、频控默认）走全局。

5.9 数据库连接层（config/database.yml）

实测全文见部署篇第八章：adapter: mysql2、encoding: utf8mb4、collation: utf8mb4_unicode_ci、三环境库 qpixel_dev/qpixel_test/qpixel，账号 qpixel 与密钥层 docker/env 必须一致；redis_* 块指向编排服务名 redis:6379。rake db:version 实测：

database: qpixel_dev
Current version: 20260614135514

5.10 Puma / ActionCable 层

config/puma.rb 实测：ENV.fetch("RAILS_MAX_THREADS"){5}、ENV.fetch("PORT"){3000}、pidfile ENV.fetch("PIDFILE"){"tmp/pids/server.pid"}；workers ENV.fetch("WEB_CONCURRENCY"){2} 一行被注释，即默认单进程线程模式（启动日志 Puma starting in single mode... Min threads: 5 / Max threads: 5 印证）。config/cable.yml：url: <%= ENV.fetch("REDIS_URL"){ "redis://localhost:6379/1" } %>。

5.11 AppConfig.server_settings（4 键，实测值）

5.12 AppConfig.preferences（10 项用户偏好默认）

schema：每项含 type（boolean|string|integer|choice）、description、default（必须字符串，yml 头注释原文 "All default values must be strings"）、作用域三选一（global/community/category）。实测文件清单：

5.13 AppConfig.spam_protection / safety_center

spam_protection.yml 实测 4 键：

safety_center.yml：举报中心的状态机（new/assigned/resolved 等 statuses 的 name/description/color/icon）与角色定义。文件头注释明确红线：可以增项，但默认项不可删除或改名——多处代码按 key 硬编码引用。

5.14 环境变量层核心变量

5.15 存储层（config/storage.yml）

local-setup.sh 复制 storage.docker.yml 而来，默认本地磁盘卷（上传图片落 images/，见部署篇挂载表）；qpixel 亦支持 S3 类远端存储，改此文件对应 service 块即可。

六、生产配置模板

适用场景：单社区对外服务，4C8G 内存、NVMe SSD、日活千级问答流量（RAILS_ENV=production）。

.env（编排插值层）：

COMPOSE_FILE=./docker-compose.yml
LOCAL_DEV_PORT=8131
COMMUNITY_NAME=我的社区
MAILER_PROTOCOL=https
RAILS_ENV=production
CONFIRMABLE_ALLOWED_ACCESS_DAYS=0
ENV_FILE_LOCATION=./docker/env
CLIENT_DOCKERFILE=docker/Dockerfile

docker/env（密钥层，口令换强）：

MYSQL_ROOT_PASSWORD=<强口令>
MYSQL_DATABASE=qpixel
MYSQL_USER=qpixel
MYSQL_PASSWORD=<强口令>
COMMUNITY_ADMIN_USERNAME=admin
COMMUNITY_ADMIN_PASSWORD=<≥6字符强口令>
COMMUNITY_ADMIN_EMAIL=you@yourdomain.com

追加给 uwsgi 的生产 ENV（在 compose environment: 或 env 文件注入）：

ALL_REQUESTS_LOCAL=false
PERFORM_CACHING=true
MAILER_DELIVERY_METHOD=smtp
MAILER_HOST=qa.yourdomain.com
RAILS_MAX_THREADS=8

config/config/server_settings.yml：network_base_domain 改你的基础域（如 yourdomain.com）；registration_rate_limit 保持 3600 或按注册压力调低；db_backups_path 指向真实备份盘（如 /var/sql-backups，需存在且可写）。

数据库层关键项（上线后 /admin/settings 或 rails runner 逐项落值）：

RequestContext.community = Community.first
SiteSetting['SiteName'] = '我的社区'
SiteSetting['NetworkName'] = '我的网络'
SiteSetting['AdministratorContactEmail'] = 'you@yourdomain.com'
SiteSetting['NoReplySenderEmail'] = 'noreply@yourdomain.com'   # 注意键名大小写
SiteSetting['AllUsersSenderEmail'] = 'announce@yourdomain.com'
SiteSetting['ContentLicenseName'] = 'CC BY-SA 4.0'
SiteSetting['SsoSignIn'] = false        # 不接 Codidact SSO 则关闭
SiteSetting['AllowContentTransfer'] = false

其余按第五章表格逐项对照：RL_NewUser* 组按运营预期放宽一档、EnableMandatoryGlobalAdminMod2FA 置 true、RestrictedAccess 按需。

注意：官方 compose 路线自述面向开发场景（docker/README.md 末节：未经 production 模式验证、邮件默认走 letter_opener_web）。上表 production 化改动需自行回归；RAILS_ENV=production 时还需 SECRET_KEY_BASE/凭据与 rails assets:precompile，不在本文实测范围。

七、常见问题

Q1：SiteSetting['site_name'] 返回 nil。 A：键大小写敏感，实测 'site_name' → nil、'SiteName' → "QPixel"。全量正确键名见 4.2 表。

Q2：rails runner 里读设置报 undefined method for nil 或读到错误社区。 A：脚本入口未设社区上下文。官方 README 与模型代码都要求先 RequestContext.community = Community.first（本文 5.2 实测即此写法）；SiteSetting[] 的缓存键与回退查询都依赖 RequestContext.community_id。

Q3：改了 config/config/server_settings.yml 不生效。 A：AppConfig 只在启动时经 initializer 加载一次（3.2 节源码），重启应用即生效。

Q4：preferences.yml 里把 default 写成裸布尔 true 报错/行为怪。 A：文件头注释硬性要求 所有默认值必须是字符串（'true'），由运行时按 type 转换。

Q5：safety_center.yml 删掉一个默认 status 后举报页 500。 A：默认项被代码按 key 硬编码引用（文件头注释原话 "should NOT be removed or altered"），只增不删。

Q6：改了设置页面没立刻变化。 A：SiteSetting 读取走 Rails.cache（键 SiteSettings/<community>/<Name>），[]= 会同步写缓存；但直接改库（SQL UPDATE）不会刷缓存，需重启或走 []=/UI 改。网络缓存类问题可用 rails r scripts/clear_cache.rb（实测 exit=0，清 network/* 与 pinned_links）。

Q7：想给第二个社区设不同站名。 A：本表按 (community_id, name) 唯一，社区级行覆盖全局行（实测 global=26/scoped=86）；在对应社区上下文里 SiteSetting['SiteName'] = ... 即写入该社区行。

八、参考链接

• qpixel 仓库：https://github.com/codidact/qpixel
• SiteSetting 模型源码：https://github.com/codidact/qpixel/blob/develop/app/models/site_setting.rb
• AppConfig initializer：https://github.com/codidact/qpixel/blob/develop/config/initializers/config.rb
• 官方 Docker 说明（含 ENV 表）：https://github.com/codidact/qpixel/blob/develop/docker/README.md
• 站内互链：《qpixel 介绍与选型指南》、《qpixel 0.13.0 Docker Compose 部署指南》、《qpixel 0.13.0 常用 CLI 命令与工具详解》