ITFlow 26.10 配置参数详解

目标：把一台已按 《Ubuntu 22.04 安装 ITFlow 26.10 指南》 装好的 ITFlow 26.10 的全部配置面讲透：config.php 逐参数实测回显与代码引用点、数据库内业务设置（settings 表）、PHP 运行时参数、Web 层参数与后台任务配置。本文所有文件内容与查询结果均在 Ubuntu 22.04.5 LTS 实机实例（ITFlow v26.10，git 标签）上实测采集。

一、环境信息

二、配置体系总览

ITFlow 26.10 的配置分散在五个层面，改动频率与作用域从上到下递增：

💡 技术拓展：ITFlow 把「基础设施参数」（改完就不用再动的）放在 config.php 文件里，把「业务参数」（管理员会经常在界面里调的）放进数据库——这是老派 PHP 应用常见的两层拆分。好处是业务参数有多公司扩展位（settings 表带 company_id 键），基础设施参数则不占数据库、实例挂了也能靠文件快速还原连接信息。

三、config.php 逐参数详解

安装完成后的实测文件全文（sudo cat /var/www/html/config.php，口令为示例值）：

<?php

$dbhost = 'localhost';
$dbusername = 'itflow';
$dbpassword = 'q1w2e3r4';
$database = 'itflow';
$mysqli = mysqli_connect($dbhost, $dbusername, $dbpassword, $database) or die('Database Connection Failed');
$config_app_name = 'ITFlow';
$config_base_url = 'localhost:8146';
$config_https_only = FALSE;
$repo_branch = 'master';
$installation_id = '_huZR6xLmroUH9QcSM9Vc5Z9nqqchHoE';
$config_enable_setup = 0;


// Backup encryption key - keep a copy somewhere safe, backups cannot be restored without it
$config_backup_key = 'RLieWPf4cnw33NViIAS7zSbjEQ9Holnw';

💡 说明：$config_base_url = 'localhost:8146' 与 installation_id 的具体值因实例而异——前者由向导按你访问安装页所用的 Host 头自动生成（代码出处 setup/index.php：$config_base_url = $_SERVER['HTTP_HOST'];），后者每次安装随机生成；$config_https_only 实测实例为 FALSE（为配合 HTTP 测试访问手工关闭，见 3.7）；$config_backup_key 在第一次构建备份后自动追加（见 3.10）。

逐参数说明如下：

3.1 $dbhost —— 数据库主机

• 实测生成值：'localhost'。
• 作用：MariaDB 连接目标。本机库用 localhost（走 socket），独立数据库服务器填其 IP/主机名。
• 改动影响：下一请求起用新连接目标；填错时页面会报 Database Connection Failed（代码中 mysqli_connect 失败即 die）。

3.2 $dbusername / 3.3 $dbpassword —— 数据库账号与口令

• 实测生成值：'itflow' / 'q1w2e3r4'（示例口令，生产请用强口令）。
• 作用：连接 MariaDB 的专用账号，安装时建库赋权的那组凭据（GRANT ALL PRIVILEGES ON itflow.* TO 'itflow'@'localhost'）。
• 改动实测：在 MariaDB 侧改口令后必须同步改这里，否则全站报 Database Connection Failed。

3.4 $database —— 数据库名

• 实测生成值：'itflow'（安装后 141 张表，SHOW TABLES 实测）。

3.5 $mysqli —— 连接句柄变量

• 作用：全站共用的 mysqli 连接对象。它在 config.php 内即完成连接（非惰性），所以 config.php 一旦加载必然伴随一次真实数据库连接——这也是排障时「改完 config.php 白屏但 nginx 日志无错」时应先想到的检查点。

3.6 $config_app_name —— 应用实例名

• 实测生成值：'ITFlow'。
• 作用：实例显示名。官方文档描述为 "Name of your app, will appear in various places (e.g. myITFlow)"；在 26.10 代码里它主要出现在系统发出的邮件模板中（如 agent/user/post/profile.php 里账号变更确认邮件的主题 "…account update confirmation for…" 与正文），页面标题栏则显示的是公司名（settings 表中的公司信息）而非该值。
• 改动实测：将值改为 ITFlow Lab 后刷新页面 200 正常，改动即生效；随后已复原为 ITFlow。

3.7 $config_https_only —— HTTPS 强制开关

• 实测生成值：向导生成 TRUE；本实测实例改为 FALSE（配合纯 HTTP 访问）。
• 作用：TRUE 时登录 Cookie 带 secure 属性（实测登录响应头 Set-Cookie: PHPSESSID=…; secure），纯 HTTP 环境浏览器不会回传 Cookie，登录页会直接显示限制文案——实测原文：

Login is restricted as ITFlow defaults to HTTPS-only for enhanced security. To login using HTTP, modify the config.php file by setting config_https_only to false. However, this is strongly discouraged, especially when accessing from potentially unsafe networks like the internet.

• 改法：sudo sed -i 's/$config_https_only = TRUE;/$config_https_only = FALSE;/' /var/www/html/config.php，改完免重启立即生效（实测改后登录即恢复 302 → /agent/clients.php）。生产环境应保持 TRUE 并为站点配 HTTPS。

3.8 $repo_branch —— 更新跟踪分支

• 实测生成值：'master'。
• 作用：自更新机制跟踪的 Git 分支。代码出处 functions/app.php（"The branch this install tracks"），CLI 更新脚本 scripts/update_cli.php 按它决定代码硬重置的目标。
• 改动影响：想跟 develop 测试线就改成 'develop'（官方 config_php 文档口径），改完与 Maintenance > Update / update_cli.php 的更新目标联动。

3.9 $installation_id —— 安装标识

• 实测生成值：'_huZR6xLmroUH9QcSM9Vc5Z9nqqchHoE'（每次安装随机）。
• 作用： opted-in 遥测时标识本安装（官方口径 "Used to track your installation when opted in to telemetry"）。不参与任何本地业务逻辑，无需修改。

3.10 $config_backup_key —— 备份加密密钥

• 实测值：首次成功构建备份后由系统自动追加（实测追加行 $config_backup_key = 'RLieWPf4cnw33NViIAS7zSbjEQ9Holnw';）。
• 作用：备份 ZIP（如实测生成的 itflow_20261023-233527_full_m-gi5Kk0HsVtFbW7qhioTff0oEhjrpaW.zip）的解密密钥。恢复侧脚本 scripts/restore_cli.php 用它解包，密钥丢失则备份不可恢复——文件内注释原文 "backups cannot be restored without it"。
• 运维要求：立即抄录到密码库之外的安全位置，并把该行纳入日常备份核验。

3.11 $config_enable_setup —— 安装向导开关

• 实测生成值：0（向导完成即关闭）。
• 作用：防止已安装实例被重新初始化（官方口径 "Used to prevent re-setting up ITFlow once installed & setup"）。实测验证：装好的实例访问 /setup/?checks 会直接 302 跳回 /login.php。
• ⚠️ 注意：手工把它改回 1 会重新开放向导，等于允许他人通过 Web 重新初始化你的实例（有覆盖风险），除灾备演练外不要开启。

3.12 可选扩展参数（安装时不生成，按需手工追加）

以下两项不在向导产物中，需要时按官方 config_php 文档追加到 config.php：

四、数据库内业务设置（settings 表）

业务设置全部落在 MariaDB 的 settings 表（实测 100 个字段，单行，company_id=1）。日常通过 Web 后台对应页面修改，本节给出运维最常触碰的字段组与实测值：

sudo mariadb -u root itflow -e "SELECT config_current_database_version, config_enable_cron, config_backup_retention_days, config_backup_retention_count, config_backup_cron_type, config_ticket_email_parse, config_module_enable_itdoc, config_module_enable_accounting, config_client_portal_enable, config_default_net_terms, config_invoice_late_fee_enable FROM settings WHERE company_id=1 \G"

实测回显：

*************************** 1. row ***************************
config_current_database_version: 2.7.9
             config_enable_cron: 1
   config_backup_retention_days: 30
  config_backup_retention_count: 5
        config_backup_cron_type: full
      config_ticket_email_parse: 0
     config_module_enable_itdoc: 1
config_module_enable_accounting: 1
    config_client_portal_enable: 1
       config_default_net_terms: 30
 config_invoice_late_fee_enable: 0

字段分组速查（实测字段名 → 含义 → 对应后台入口）：

⚠️ 注意：settings 表是应用私有结构，跨版本字段会随迁移增减（26.10 为 100 列）。直接改库属高级操作，常规变更一律走 Web 后台；改库前先做备份（见 Maintenance > Backup 或 B 篇 4.11 节）。

五、PHP 运行时参数

Web 侧配置文件 /etc/php/8.3/fpm/php.ini，官方建议按 500M 上传、300 秒超时调整，实测修改并生效后的三项：

grep -E '^(upload_max_filesize|post_max_size|max_execution_time)' /etc/php/8.3/fpm/php.ini

实测回显：

max_execution_time = 300
post_max_size = 500M
upload_max_filesize = 500M

• upload_max_filesize / post_max_size：单文件与整请求体上限，影响附件上传、备份包恢复等场景，改完必须 systemctl restart php8.3-fpm（实测 restart 返回 rc=0）。
• max_execution_time：脚本最长执行时间，300 秒是为了给大文件上传/导入留余量。
• 提醒：CLI 侧（cron 任务）读的是 /etc/php/8.3/cli/php.ini，两份文件独立，需要时分开调整；Nginx 侧还有配套的 client_max_body_size（见第六节），两头都要放开才能真正传大文件。

六、Web 层参数（Nginx）

实测站点文件 /etc/nginx/sites-available/itflow.conf 全文：

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name _;
    root /var/www/html;
    index index.php index.html;

    client_max_body_size 500M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

参数要点：

改动后固定两连：sudo nginx -t（实测输出 syntax is ok / test is successful）→ sudo systemctl reload nginx。

七、后台任务配置

后台任务由「系统 crontab + 应用内开关」两段拼成：

1. crontab 条目（向导第 6 步页面原文给出的官方形态）：* * * * * php /var/www/html/cron/cron.php >/dev/null。实测按 /etc/cron.d 形态落盘为：

* * * * * www-data php /var/www/html/cron/cron.php >/dev/null

注意用户字段：必须以站点文件属主（www-data）运行——实测 root 与 www-data 混跑会因 /tmp 下 itflow_cron_<hash>.lock 锁文件属主冲突导致调度被拒（实测报错与解法见 B 篇 FAQ Q3）。

2. 应用内开关与调度：settings.config_enable_cron 总开关（实测打开后为 1）+ cron_jobs 表逐任务启停/调度（mail_queue、ticket_sla、ticket_email_parser 每分钟；nightly_tasks/domain_refresher/certificate_refresher/update_check 每日；backup/app_update 按需）。逐任务的 CLI 直跑回显与字段说明见同专栏 《ITFlow 26.10 常用 CLI 命令与工具详解》。

八、常见问题（FAQ）

Q1：改了 config.php 要重启服务吗？

不需要。PHP 每次请求都会重新加载 config.php，实测将 $config_https_only 由 TRUE 改 FALSE 后登录行为立即变化（无需任何重启）。仅 PHP 运行时参数（php.ini）需要 restart php8.3-fpm。

Q2：页面报 Database Connection Failed？

按顺序核对：MariaDB 是否在跑（systemctl is-active mariadb，实测运行态输出 active）→ config.php 的 $dbhost/$dbusername/$dbpassword/$database 是否与库内账号一致 → 账号是否有 itflow.* 库内权限。三者对上即恢复。

Q3：备份包找不到解不开？

备份 ZIP 在站点 uploads/backups/ 下（实测文件名形如 itflow_20261023-233527_full_<随机串>.zip），解密密钥就是 config.php 的 $config_backup_key。用 php scripts/restore_cli.php --file=<备份包> --inspect 先检视内容，确认无虞再加 --yes 实际恢复。

Q4：想换站点域名/端口？

改两处：① Nginx 站点的 server_name 与监听端口；② config.php 的 $config_base_url（它决定系统生成的外部链接，如实测数据里 guest 发票链接即以它拼出）。改完在浏览器用新地址重登一次确认 Cookie 正常（HTTPS 站点保持 $config_https_only = TRUE）。

Q5：遥测想关掉/开启？

安装向导第 6 步的选择决定是否上报；事后在后台 Settings 的遥测页（settings_telemetry）调整。$installation_id 仅为遥测标识，改动不影响业务。

九、参考链接

1. 官方 config.php 说明：https://docs.itflow.org/config_php （查询日期 2026-10-23）
2. 官方 cron 文档：https://docs.itflow.org/cron （查询日期 2026-10-23）
3. 官方邮件配置（SMTP/IMAP）：https://docs.itflow.org/email_config 与 https://docs.itflow.org/ticket_email_parse （查询日期 2026-10-23）
4. 源码仓库（参数引用点定位）：https://github.com/itflow-org/itflow （v26.10 标签，查询日期 2026-10-23）
5. 同专栏 《ITFlow 26.10 介绍与选型指南》、《Ubuntu 22.04 安装 ITFlow 26.10 指南》