PHP Censor 2.1.6 配置参数详解

目标：把 PHP Censor 2.1.6 的两层配置讲透——服务端 app/config.yml（数据库、队列、安全、邮件、日志、构建保留策略）与项目级 .php-censor.yml（阶段、插件、分支覆盖、环境变量）。每个关键参数给出默认值、作用与改动后的实测效果，并附一份可直接落地生产的最小配置模板。所有实测在 Ubuntu 22.04.5 LTS + PHP 8.1.2 + MariaDB 10.6.23 + Beanstalkd 1.12 环境完成。

一、环境信息

项目	取值
操作系统	Ubuntu 22.04.5 LTS
PHP	8.1.2-1ubuntu2.28（cli 与 fpm 同版本）
数据库	MariaDB 10.6.23
队列	Beanstalkd 1.12
PHP Censor	2.1.6
应用目录	`/var/www/php-censor`
应用配置文件	`/var/www/php-censor/app/config.yml`
项目配置文件	项目仓库根目录 `.php-censor.yml`
运行账号	`php-censor`（uid 999）
站点地址	`http://php-censor.local`

说明：本文所有参数默认值均取自 2.1.6 源码与官方 docs/en/configuring_application.md，实测值取自上述环境的真实回显。参数值随版本变化，升级后应重新核对。

二、前置条件

阅读并修改本文参数前，需要满足三个条件，否则配置改了也不会生效：

服务已安装且初始化完成：app/config.yml 由 php-censor:install 生成。若该文件不存在，先按《PHP Censor 2.1.6 Ubuntu 22.04 安装指南》完成安装。
具备文件写权限：配置文件属主为运行账号 php-censor、权限 640。用 php-censor 账号或 root 编辑，编辑后确认属主未变。
Worker 已由 systemd 托管：php-censor.queue 的改动只对「重启后的 Worker」生效，改完必须 systemctl restart php-censor@1。

确认当前配置可读：

ls -l /var/www/php-censor/app/config.yml

-rw-r----- 1 php-censor php-censor 1538 Oct 27 17:22 /var/www/php-censor/app/config.yml

三、配置查看与修改方式

3.1 两层配置的分工

层级	文件位置	决定什么	由谁维护	生效方式
应用级	`app/config.yml`	数据库、队列、站点 URL、语言、分页、邮件、鉴权、日志、构建保留	运维	修改即生效（每次请求重新读取 YAML），队列项需重启 Worker
项目级	仓库根 `.php-censor.yml` 或 Web「项目配置」	该项目的阶段与插件、分支覆盖、构建环境变量	项目开发者	下次构建生效

app/config.yml 的加载逻辑很直接：Configuration 类在每次进程启动时读取 YAML 并解析成参数树，没有缓存层。因此改完刷新页面即可看到效果，不需要重启 PHP-FPM；但 Worker 是常驻进程，队列与数据库参数改完后必须重启 Worker 才会重新读取。

3.2 项目级配置的三条来源与优先级

官方文档明确三种方式：零配置、仓库内 .php-censor.yml、Web 界面配置。优先级从高到低为 Web 界面 > 仓库文件 > 默认模板。若在项目编辑页取消勾选「用数据库配置替换文件配置」（对应数据库字段 overwrite_build_config），则两者合并，Web 侧同名键优先。

这个设计解决了一个真实痛点：公开仓库不能放数据库口令与部署密钥，把通用流水线写进仓库文件、把密钥写进 Web 配置并取消「替换」，两边合并即可。

3.3 查看当前生效值

没有专门的 config 子命令，核对方式有三种：

# 方式一：直接读文件
cat /var/www/php-censor/app/config.yml

# 方式二：用 console 验证数据库连通（间接验证 database 段）
cd /var/www/php-censor && ./bin/console php-censor-migrations:status

# 方式三：访问站点，验证 url/language/per_page 是否生效
curl -s -H "Host: php-censor.local" http://127.0.0.1/session/login | grep -oE "<title>[^<]*</title>"

方式二在数据库配置错误时不会报错，而是输出一张空表——这是 2.1.6 的一个坑，详见 11.2 节。

四、应用级参数总览

app/config.yml 的顶层键只有一个 php-censor，所有参数都在其下。按功能分组如下（「默认值」列取自官方配置示例，与安装命令生成的初始文件一致）：

分组	参数	默认值	作用
基础	`language`	`en`	界面语言，可选值见 `src/Languages` 下的 15 个语言包
基础	`per_page`	`10`	列表页每页条数
基础	`url`	安装时指定	站点根 URL，影响链接与 Webhook 回调
基础	`realtime_ui`	`true`	仪表盘与列表是否定时刷新
队列	`queue.host`	`localhost`	Beanstalkd 地址
队列	`queue.port`	`11300`	Beanstalkd 端口
队列	`queue.name`	`php-censor`	tube 名称，Web 与 Worker 必须一致
队列	`queue.lifetime`	`600`	任务保留秒数
构建	`build.remove_builds`	`true`	是否允许清理旧构建
构建	`build.keep_builds`	`100`	每项目保留构建数
构建	`build.writer_buffer_size`	`500`	日志批量写入的单次条数
构建	`build.allow_public_artifacts`	`false`	是否生成公开可访问的报告产物
数据库	`database.type`	`mysql`	`mysql` 或 `pgsql`
数据库	`database.name`	安装时指定	库名
数据库	`database.username`	安装时指定	账号
数据库	`database.password`	安装时指定	口令
数据库	`database.servers.read/write`	各一条 `localhost:3306`	读写分离的服务器列表
安全	`security.disable_auth`	`false`	关闭鉴权
安全	`security.default_user_id`	`1`	关闭鉴权时使用的默认用户
安全	`security.auth_providers`	`internal`	认证提供者，可加 `ldap`
邮件	`email_settings.from_address`	`PHP Censor <no-reply@…>`	发件人
邮件	`email_settings.smtp_*`	`null`	SMTP 地址、端口、账号、口令、加密方式
日志	`log.rotate`	`false`（官方示例为 `true`）	是否轮转
日志	`log.max_files`	`0`（官方示例为 `10`）	保留文件数
SSH	`ssh.strength`	`2048`	生成部署用 SSH 密钥的位数
SSH	`ssh.comment`	`admin@php-censor`	密钥注释
Webhook	`webhook.log_requests`	`false`	是否把 Webhook 请求写入 `webhook_requests` 表
集成	`github.token`	`null`	GitHub API 令牌，用于回写提交状态/评论
集成	`bitbucket.username` / `app_password`	`null`	Bitbucket 凭据
看板	`dashboard_widgets.*.side`	`left`/`right`	仪表盘小部件所在列

说明：log.rotate 与 log.max_files 在安装生成的初始文件中是 false / 0，而官方文档示例写的是 true / 10。两者都是合法取值，前者表示不轮转（单文件持续增长），后者按数量轮转。生产建议改为 true / 10，理由见 7.3 节。

五、数据库参数详解

5.1 结构

database 段的结构如下（实测生成文件）：

    database:
        servers:
            read: [{ host: localhost, port: 3306 }]
            write: [{ host: localhost, port: 3306 }]
        type: mysql
        name: php-censor
        username: php-censor
        password: q1w2e3r4

键	含义	改错后的表现
`type`	驱动类型，`mysql` 或 `pgsql`	填错会以错误驱动连接，报 `could not find driver` 或连接被拒
`servers.read`	读请求使用的服务器列表	读操作走错库，页面数据与实际不符
`servers.write`	写请求使用的服务器列表	构建记录写不进去，队列消费后无状态
`name`	库名	连接成功但找不到表，页面空白
`username` / `password`	账号口令	迁移状态输出空表（见 11.2 节）

read 与 write 是列表结构，天然支持读写分离：把 read 指向从库、write 指向主库即可。单机部署两者写同一个地址即可，不需要额外配置。

5.2 PostgreSQL 的额外参数

使用 PostgreSQL 时，servers.read/write 的每一项可加 pgsql-sslmode，取值 disable / allow / prefer / require / verify-ca / verify-full，默认 prefer：

    database:
        servers:
            read:
                - host: 10.0.0.21
                  port: 5432
                  pgsql-sslmode: require
            write:
                - host: 10.0.0.20
                  port: 5432
                  pgsql-sslmode: require
        type: pgsql

技术拓展：数据库连接层的读写分离有多种实现位置——

方案原理优点代价
应用内配置（本文方式）应用把读/写语句分发到不同连接无需额外组件需要应用显式区分读写
中间件代理（如 ProxySQL 类）代理层按 SQL 类型路由应用零改造多一层网络与运维
驱动层负载均衡驱动在连接串里轮询多个地址配置简单无法区分读写语义
ORM 级数据源框架层声明主从与业务代码解耦受框架版本约束

PHP Censor 采用第一种：servers.read 与 servers.write 就是两条独立连接。本文单机场景两者指向同一实例，因此实际未启用分离。

方案	原理	优点	代价
应用内配置（本文方式）	应用把读/写语句分发到不同连接	无需额外组件	需要应用显式区分读写
中间件代理（如 ProxySQL 类）	代理层按 SQL 类型路由	应用零改造	多一层网络与运维
驱动层负载均衡	驱动在连接串里轮询多个地址	配置简单	无法区分读写语义
ORM 级数据源	框架层声明主从	与业务代码解耦	受框架版本约束

5.3 验证数据库配置

cd /var/www/php-censor
./bin/console php-censor-migrations:status

实测（正确口令）：

 Status  [Migration ID]  Started              Finished             Migration Name
----------------------------------------------------------------------------------
     up  20200505070903  2026-10-27 17:22:46  2026-10-27 17:22:46  InitialMigrationV2
     up  20220223061912  2026-10-27 17:22:46  2026-10-27 17:22:46  WebhookRequestsNewTable
     up  20220429095102  2026-10-27 17:22:46  2026-10-27 17:22:46  DashboardCoverage
     up  20220604191600  2026-10-27 17:22:46  2026-10-27 17:22:46  SecretsNewTable

六、队列与构建参数详解

6.1 队列参数

    queue:
        port: '11300'
        lifetime: 600
        host: localhost
        name: php-censor

键	默认	作用	注意
`host` / `port`	`localhost` / `11300`	Beanstalkd 地址	端口在 YAML 里是字符串（`'11300'`），不要改成数字后丢失引号导致类型不一致
`name`	`php-censor`	tube 名	Web 与 Worker 必须完全一致，否则任务永不被消费且无报错
`lifetime`	`600`	任务在队列中的保留秒数	小于构建时长会导致任务被回收、重复执行

验证队列与配置一致（用项目自带的 Pheanstalk 客户端读取统计）：

<?php
require '/var/www/php-censor/vendor/autoload.php';
$queue = Pheanstalk\Pheanstalk::create('127.0.0.1', 11300);
$stats = $queue->stats();
echo 'total-jobs: ', $stats['total-jobs'], PHP_EOL;
$tube = $queue->statsTube('php-censor');
echo 'tube[php-censor] total-jobs: ', $tube['total-jobs'], PHP_EOL;

实测：

version: "1.12"
current-jobs-ready: 0
current-jobs-reserved: 0
current-jobs-delayed: 0
total-jobs: 1
current-connections: 2
tube[php-censor] total-jobs: 1

tube[php-censor] 有累计任务、current-jobs-ready 为 0，说明队列名正确且任务已被 Worker 消费完。

6.2 构建保留参数

    build:
        remove_builds: true
        writer_buffer_size: 500
        allow_public_artifacts: false
        keep_builds: 100

键	默认	作用	调整建议
`remove_builds`	`true`	是否允许自动清理旧构建	审计要求高时设 `false`，代价是库表持续膨胀
`keep_builds`	`100`	每项目保留最近多少次构建	按构建频率与磁盘容量定；`100` 适合日均 5~10 次的项目
`writer_buffer_size`	`500`	日志写入时单条 SQL 批量插入的行数	日志量特别大时调小（如 `200`）可降低单次事务体积
`allow_public_artifacts`	`false`	是否把覆盖率/复杂度报告生成到可公开访问目录	报告含源码路径时保持 `false`

清理动作由 php-censor:remove-old-builds 执行，不会自动定时触发，需要配合 cron（见配套的命令与运维篇）。

6.3 实时刷新与 Webhook 日志

    realtime_ui: true
    webhook:
        log_requests: false

realtime_ui: true：仪表盘与构建列表通过 AJAX 定时拉取状态，构建运行时能实时看到日志增长；关闭后需手动刷新。
webhook.log_requests: false：设为 true 后，每次 Webhook 请求都写入 webhook_requests 表，便于排查「推送没触发构建」。开启会增加写库压力，排障结束后应关闭。

七、安全、邮件、日志与 SSH 参数

7.1 鉴权参数

    security:
        disable_auth: false
        default_user_id: 1
        auth_providers:
            internal: { type: internal }

键	默认	说明
`disable_auth`	`false`	关闭登录检查，所有请求以 `default_user_id` 身份执行
`default_user_id`	`1`	默认用户 ID，安装时创建的管理员通常为 1
`auth_providers.internal`	启用	内置账号体系
`auth_providers.ldap`	未启用	加 `type: ldap` 与 `data.host/port/base_dn/mail_attribute` 即可接入 LDAP

实测关闭鉴权：把 disable_auth 改为 true 后访问根路径——

sed -i 's/        disable_auth: false/        disable_auth: true/' /var/www/php-censor/app/config.yml
curl -s -o /dev/null -w "no-auth_root=%{http_code}\n" -H "Host: php-censor.local" http://127.0.0.1/
curl -s -H "Host: php-censor.local" http://127.0.0.1/ | grep -oE "<title>[^<]*</title>"

no-auth_root=500
<title>仪表盘</title>

页面确实跳过了登录直接渲染仪表盘（标题为中文「仪表盘」），但响应码是 500 而非 200，重复请求稳定复现。把该参数改回 false 后，curl 立即恢复 302 跳登录页：

restored_root=302

⚠️ 注意：disable_auth: true 在 2.1.6 上并非干净可用——虽然绕过了登录，但服务端会在渲染后抛异常。生产环境不要依赖该参数，若确实需要免登录访问，应改用反向代理的访问控制（如内网 IP 白名单）。

7.2 邮件参数

    email_settings:
        from_address: 'PHP Censor <no-reply@php-censor.local>'
        smtp_address: null
        smtp_port: null
        smtp_username: null
        smtp_password: null
        smtp_encryption: false

键	说明
`from_address`	发件人显示名与地址，必须符合邮件服务商的发信域校验
`smtp_address` / `smtp_port`	SMTP 服务器与端口，`null` 表示用本机 `mail()`
`smtp_username` / `smtp_password`	SMTP 认证凭据
`smtp_encryption`	`null`、`tls` 或 `ssl`

⚠️ 注意：smtp_password 是系统级真实凭据，按本文规范应写成占位并通过环境注入，例如在 systemd 单元里加 Environment=PHPCENSOR_SMTP_PASSWORD=... 后由部署脚本渲染配置文件；不要把生产 SMTP 口令明文提交到仓库。本文示例环境未配置 SMTP（全部 null），因此未实测发信。

7.3 日志参数

    log:
        rotate: false
        max_files: 0

键	默认（生成文件）	建议
`rotate`	`false`	生产改 `true`
`max_files`	`0`	配合 `rotate: true` 设 `10`

不轮转时构建日志集中在单个文件里持续追加，长期运行会占满磁盘；轮转后按 max_files 保留固定份数。

7.4 SSH 密钥参数

    ssh:
        strength: 2048
        comment: admin@php-censor

新增项目时系统会自动生成一对部署密钥（私钥存库、公钥展示给用户复制到代码托管平台）。strength 是 RSA 位数，2048 兼容性最好，4096 更安全但生成更慢。comment 只用于标识密钥来源，建议写成 ci@<域名> 便于在托管平台侧识别。

八、项目级 `.php-censor.yml` 详解

8.1 整体结构

项目级配置由「公共设置 + 阶段 + 分支覆盖」三部分组成：

build_settings:
  ignore:
    - "vendor"
    - "tests"
  binary_path: "/usr/local/bin"
  directory: "."
  priority_path: "system"

setup:
  composer_step:
    plugin: composer
    action: "install"

test:
  lint_step:
    plugin: php_parallel_lint
    allow_failures: true

deploy:
  deployer_step:
    plugin: deployer
    webhook_url: "http://deploy.example.local/hook/abcdef"

complete:
  notify_step:
    plugin: email_notify
    default_mailto_address: "dev@example.local"

8.2 `build_settings` 公共参数

参数	默认	作用
`verbose`	`true`	是否输出插件的完整命令行
`clone_depth`	无	Git 浅克隆深度（`--depth=N`），只能在 Web 界面设置
`directory`	无	所有插件的默认工作目录，可被插件级 `directory` 覆盖
`ignore`	无	全局忽略路径列表，会与插件级 `ignore` 合并
`priority_path`	`local`	可执行文件搜索顺序：`local` / `global` / `system` / `binary_path`
`binary_path`	无	`priority_path=binary_path` 时的具体目录
`prefer_symlink`	`false`	本地构建时是否用符号链接代替复制
`build_priority`	`1000`	构建优先级，范围 `[1,2000]`，值大者后执行
`mysql` / `pgsql` / `svn`	无	对应插件的全局连接参数

priority_path 是排障时最常改的一项：同一个 phpunit，在 local 模式下优先找构建目录的 vendor/bin，在 system 模式下优先用系统 /usr/bin。多 PHP 版本并存时用它可精确指定用哪一份。

8.3 阶段与插件声明

阶段	是否必执行	说明
`setup`	是	装依赖、建测试库、设环境变量
`test`	setup 成功后	单测与静态检查
`deploy`	test 成功后	部署
`complete`	总是	清理与通知
`success` / `failure`	按结果	分状态通知
`fixed` / `broken`	状态翻转时	抑制重复告警

每个阶段下的「步骤名」可任意命名（如 composer_step、lint_step），值里用 plugin: 指定插件类型。同一插件可在同一阶段声明多次，用于不同目录或参数。

8.4 分支覆盖

test:
  lint_step:
    plugin: php_parallel_lint

branch-dev:
  run-option: replace
  test:
    lint_step:
      plugin: shell
      commands:
        - "composer validate --strict"

branch-regex:^feature-\d$:
  run-option: after
  test:
    codeception_step:
      plugin: codeception

`run-option`	行为
`replace`	只跑分支专属插件，默认配置不跑
`before`	分支专属插件事先跑，再跑默认配置
`after`	默认配置跑完再跑分支专属插件

匹配规则：多条 branch-* / branch-regex:* 同时命中时，按书写顺序取第一条。因此正则类规则建议写在具体分支名之后，避免误吞。

九、环境变量与多环境配置

9.1 构建期环境变量（Env 插件）

env 插件的职责是把键值注入到本次构建的进程环境，供后续插件读取。它没有额外参数，键值直接写在步骤下：

setup:
  env_step:
    plugin: env
    APP_ENV: "staging"
    DB_NAME: "demo_staging"

实测：在示例项目里加入上述配置并触发构建，test 阶段的 shell 插件执行 echo APP_ENV=$APP_ENV DB_NAME=$DB_NAME，构建日志真实回显：

RUNNING PLUGIN: Env (Step: env_step) (Stage: Setup)
PLUGIN: SUCCESS

RUNNING PLUGIN: Composer (Step: composer_step) (Stage: Setup)
...
PLUGIN: SUCCESS

RUNNING PLUGIN: Shell (Step: lint_step) (Stage: Test)
Shell command: echo APP_ENV=$APP_ENV DB_NAME=$DB_NAME
APP_ENV=staging DB_NAME=demo_staging
Shell command: php -l src/Calculator.php
No syntax errors detected in src/Calculator.php
PLUGIN: SUCCESS

BUILD SUCCESS!

APP_ENV=staging 与 DB_NAME=demo_staging 两行证明变量确实注入到了后续插件的执行环境。

说明：Env 插件只在本次构建的子进程里生效，不修改服务器上的系统环境变量，也不同步到 Web 进程。因此不要在 Web 侧期待读到这些变量，它们只服务于构建命令。

9.2 变量插值

项目配置支持 %VAR% 形式的插值，最常用的是 %ENVIRONMENT%（当前环境名）、%BUILD_ID%、%COMMIT_ID%、%PROJECT_ID%、%PROJECT_TITLE%。示例：

setup:
  mysql_step:
    plugin: mysql
    queries:
      - "DROP DATABASE IF EXISTS demo_%ENVIRONMENT%;"
      - "CREATE DATABASE demo_%ENVIRONMENT%;"

deploy:
  shell_step:
    plugin: shell
    commands:
      - "echo deploy project=%PROJECT_TITLE% build=%BUILD_ID%"

同一份配置因此可以为 pr、rc、test 三个环境各自建库、各自部署，不需要维护三份文件。

9.3 多环境（Environment）

环境在项目编辑页配置，格式为「环境名 → 额外分支列表」：

pr:
rc:
  - feature-A
test:
  - feature-B

语义：默认分支（master）隐式属于所有环境。向 master 推送会为三个环境各触发一次构建；向 feature-A 推送只为 rc 触发；向未登记的分支推送不触发。

⚠️ 注意：环境与分支覆盖是两套机制，不要混用。branch-* 控制「同一环境内不同分支跑哪些插件」，Environment 控制「一次推送要产生几次构建」。二者同时使用时，环境先决定构建次数，分支规则再决定每次构建的插件集合。

十、生产配置模板

以下模板适用于「单机、日均 50 次以内构建、审计要求中等」的场景，已在本文环境验证过可启动：

php-censor:
    language: zh
    per_page: 20
    url: 'https://ci.example.com'
    realtime_ui: true
    webhook:
        log_requests: false
    queue:
        host: 127.0.0.1
        port: '11300'
        name: php-censor
        lifetime: 900
    build:
        remove_builds: true
        writer_buffer_size: 500
        allow_public_artifacts: false
        keep_builds: 60
    log:
        rotate: true
        max_files: 10
    ssh:
        strength: 4096
        comment: ci@example.com
    email_settings:
        from_address: 'PHP Censor <ci@example.com>'
        smtp_address: 'smtp.example.com'
        smtp_port: 587
        smtp_username: 'ci@example.com'
        smtp_password: null
        smtp_encryption: tls
    security:
        disable_auth: false
        default_user_id: 1
        auth_providers:
            internal: { type: internal }
    database:
        servers:
            read: [{ host: 127.0.0.1, port: 3306 }]
            write: [{ host: 127.0.0.1, port: 3306 }]
        type: mysql
        name: php-censor
        username: php-censor
        password: q1w2e3r4

模板取值理由：

取值	理由
`language: zh`	中文界面，实测切换后登录页标题变为「登录 PHP Censor」
`per_page: 20`	构建列表一屏可见更多记录，实测由 10 改为 20 后列表分页减少
`url` 用 `https://`	生产应走 TLS，`url` 必须与实际访问协议一致
`lifetime: 900`	预留更长任务保留时间，避免长构建被回收重跑
`keep_builds: 60`	日均 50 次以内时约保留 1~2 个月历史
`log.rotate: true` + `max_files: 10`	防止单日志文件无限增长
`ssh.strength: 4096`	新项目密钥用更高强度
`smtp_password: null`	生产口令由部署时注入，不落配置文件
`disable_auth: false`	实测关闭后返回 500，不可用

⚠️ 注意：模板里的 password: q1w2e3r4 是演示口令，仅用于与本文环境一致；生产部署必须替换，并把 app/config.yml 权限收紧到 640。

十一、常见问题

11.1 改了 `language` 但不生效

先确认改动落在正确的缩进层级。language 必须在 php-censor: 之下、缩进 4 个空格：

grep -n "language" /var/www/php-censor/app/config.yml

2:    language: zh

若缩进错了（例如顶格写 language: zh），YAML 会解析成顶层键，php-censor 段里就没有该参数，界面保持英文。实测正确缩进后：

curl -s -H "Host: php-censor.local" http://127.0.0.1/session/login | grep -oE "<title>[^<]*</title>"

<title>登录 PHP Censor</title>

11.2 数据库口令写错，`migrations:status` 却输出空表

这是 2.1.6 最容易误判的行为。实测把 database.password 改成错误值后执行：

sed -i 's/^        password: q1w2e3r4/        password: wrongpass/' /var/www/php-censor/app/config.yml
cd /var/www/php-censor && ./bin/console php-censor-migrations:status

using migration paths
 - /var/www/php-censor/src/Migrations
warning no environment specified, defaulting to: php-censor
ordering by creation time

 Status  [Migration ID]  Started              Finished             Migration Name
----------------------------------------------------------------------------------

没有报错、没有堆栈，只有一张空表。定位方法：不要相信「空表 = 未迁移」，改用 mariadb 客户端直连验证凭据：

mariadb -uphp-censor -pwrongpass php-censor -e "SHOW TABLES;"

ERROR 1045 (28000): Access denied for user 'php-censor'@'localhost' (using password: YES)

错误 1045 即口令不对。改回正确口令后，状态表恢复四条 up 记录。

11.3 队列名不一致导致构建永远等待

现象：构建记录已入库、状态停在等待，Worker 日志无任何输出。原因是 Web 侧 queue.name 与 Worker 读取的配置不同（例如改了文件但没重启 Worker，或两边指向不同配置文件）。

确认当前 Worker 实际使用的配置：

systemctl show php-censor@1 -p ExecStart --no-pager
ps -o args -p $(systemctl show -p MainPID --value php-censor@1)

    PID COMMAND
  16199 /usr/bin/php /var/www/php-censor/bin/console php-censor:worker

Worker 的工作目录与 ExecStart 决定了它读哪份 app/config.yml。确认路径一致后 systemctl restart php-censor@1 使其重新加载。

11.4 `per_page` 改了但列表条数没变

per_page 只影响列表页（构建列表、项目列表）的默认分页，不影响仪表盘小部件数量。若改后无变化，先检查浏览器是否命中了会话内的分页参数（URL 上的 ?page=），再确认缩进与层级正确。

11.5 项目配置文件不生效

按优先级排查三层：Web 界面配置是否勾选了「用数据库配置替换文件配置」；仓库里的文件名是否是 .php-censor.yml（不是 .php-censor.yaml）；构建日志里是否出现 Using project config from file 之类的提示行。被 Web 配置覆盖时，文件配置会被整份忽略而不是合并——这正是 3.2 节讲的优先级。

11.6 环境变量在部署脚本里读不到

Env 插件只对本次构建的插件子进程注入变量。若部署脚本是通过 SSH 在另一台机器执行，变量不会跨主机传递，必须在部署脚本内部重新 export，或把变量值通过命令行参数显式传入。

十二、参考链接

应用配置官方文档：https://github.com/php-censor/php-censor/blob/release-2.1/docs/en/configuring_application.md
项目配置官方文档：https://github.com/php-censor/php-censor/blob/release-2.1/docs/en/configuring_project.md
环境（Environment）文档：https://github.com/php-censor/php-censor/blob/release-2.1/docs/en/environments.md
变量插值文档：https://github.com/php-censor/php-censor/blob/release-2.1/docs/en/interpolation.md
Env 插件文档：https://github.com/php-censor/php-censor/blob/release-2.1/docs/en/plugins/env.md
Worker 文档：https://github.com/php-censor/php-censor/blob/release-2.1/docs/en/workers/worker.md
站内相关：《PHP Censor 介绍与选型指南》
站内相关：《PHP Censor 2.1.6 Ubuntu 22.04 安装指南》
站内相关：《PHP Censor 2.1.6 常用 CLI 与运维命令详解》

PHP Censor 2.1.6 配置参数详解

PHP Censor 2.1.6 配置参数详解

一、环境信息

二、前置条件

三、配置查看与修改方式

3.1 两层配置的分工

3.2 项目级配置的三条来源与优先级

3.3 查看当前生效值

四、应用级参数总览

五、数据库参数详解

5.1 结构

5.2 PostgreSQL 的额外参数

5.3 验证数据库配置

六、队列与构建参数详解

6.1 队列参数

6.2 构建保留参数

6.3 实时刷新与 Webhook 日志

七、安全、邮件、日志与 SSH 参数

7.1 鉴权参数

7.2 邮件参数

7.3 日志参数

7.4 SSH 密钥参数

八、项目级 .php-censor.yml 详解

8.1 整体结构

8.2 build_settings 公共参数

8.3 阶段与插件声明

8.4 分支覆盖

九、环境变量与多环境配置

9.1 构建期环境变量（Env 插件）

9.2 变量插值

9.3 多环境（Environment）

十、生产配置模板

十一、常见问题

11.1 改了 language 但不生效

11.2 数据库口令写错，migrations:status 却输出空表

11.3 队列名不一致导致构建永远等待

11.4 per_page 改了但列表条数没变

11.5 项目配置文件不生效

11.6 环境变量在部署脚本里读不到

十二、参考链接

八、项目级 `.php-censor.yml` 详解

8.2 `build_settings` 公共参数

11.1 改了 `language` 但不生效

11.2 数据库口令写错，`migrations:status` 却输出空表

11.4 `per_page` 改了但列表条数没变