Cloudlog 2.8.21 配置参数详解

目标：逐项讲清 Cloudlog 2.8.21 的三个配置文件（config.php、cloudlog.php、database.php）、后台 Global Options 全局选项与 PHP 运行时参数的作用、默认值与修改影响，并给出可直接套用的生产配置模板。全部参数取自 Ubuntu 22.04 实测部署的实际文件，关键修改均经后台 Debug 页复核。

一、环境信息

• 部署形态：Ubuntu 22.04 + Apache 2.4.52（mod_php）+ PHP 8.5.12 + MariaDB 10.6.23
• Cloudlog 版本：2.8.21（安装路径 /var/www/cloudlog）
• 配置文件实测位置：
  • 主配置：/var/www/cloudlog/application/config/config.php（安装向导生成）
  • 应用级配置：/var/www/cloudlog/application/config/cloudlog.php
  • 数据库配置：/var/www/cloudlog/application/config/database.php
  • PHP 运行时：/etc/php/8.5/apache2/php.ini
• 后台核对入口：Admin → Debug Information（本篇所有「实测生效值」均以此页为准：Base URL http://127.0.0.1、Language English、数据库 cloudlog、主表 TABLE_HRD_CONTACTS_V01、字符集 utf8mb4/utf8mb4_general_ci、框架 CodeIgniter 3.2.0-dev）
• 部署/首登过程：见同专栏安装篇 《Ubuntu 22.04 安装 Cloudlog 指南》第四章

二、前置条件

• Cloudlog 已安装并可登录（向导已生成三份配置文件；本文演示账号 admin / q1w2e3r4）。
• 有服务器文件系统写权限（改配置文件用）；会话属主为 root:www-data、权限 640 的收紧态（见安装篇 7.1）——修改后保持该权限。
• 了解 PHP 配置的两份 php.ini 区别：Apache mod_php 读 /etc/php/8.5/apache2/php.ini，php --ini 打印的是 CLI 用的那份，改错文件不生效（官方 Wiki 与实测均强调此点）。

三、参数查看与修改方式

Cloudlog 的配置分四层，作用范围与查看方式不同，先建立全景再逐项解读：

修改文件类配置的通用流程：编辑 → 保存 → 刷新站点页面（框架配置无缓存，立即生效；php.ini 需重启 Apache）→ Admin → Debug Information 核对生效值。实测 Debug 页的 PHP Settings 区会直接回显 memory_limit、max_execution_time、upload_max_filesize、post_max_size、Timezone、allow_url_fopen 六项，是验证 php.ini 改动的最快途径。

⚠️ 注意：config.php 顶部定义的 $cloudlog_session_path 会拼接出会话目录（实测 Debug 页 Session Save Path 为 /tmp/cloudlog_e1c07e97f85753d494fe169196ec0f82_sessions），目录名由安装路径指纹生成，不要手工改拼串本身。

四、参数总览

三份配置文件实测内容分类汇总（默认值即实测部署中的当前值）：

config.php 业务段（选摘核心项）：

cloudlog.php 全量（8 项，实测原值）：

database.php 核心项（实测原值）：hostname → localhost、username → cloudlog、database → cloudlog、dbdriver → mysqli、dbprefix → 空。

Global Options 后台六大分类（实测页面）：Appearance（主题/外观）、Radios（电台控制）、Email（邮件服务）、Registration（注册开关）、OQRS Options（QSL 卡请求）、Version Info（版本提示定制）；另有 Public Station Diary、Public Map Confirmations 两个公开性开关。

关键差异解读：config.php 是「装好后基本不再动」的框架层；cloudlog.php 是「按需微调」的业务层；Global Options 是「日常运营」的免改文件层——按改动频率选层，能后台改的不动文件。

五、核心参数分类详解

5.1 站点基础参数

base_url 与 index_page 决定所有页面链接的形态，是最常改的两项。实测部署中：

$config['base_url']	= 'http://127.0.0.1';
$config['index_page'] = 'index.php';
$config['uri_protocol']	= 'REQUEST_URI';
$config['url_suffix'] = '';

• base_url：向导按首次访问地址生成。换域名/上 HTTPS 后必须同步改（如 https://log.example.com），否则站内跳转会回到旧地址。Debug 页 Base URL 实测即回显该值。
• index_page：配合 Apache mod_rewrite 隐藏 URL 中的 index.php，实测把第 116 行改为 $config['index_page'] = ''; 并复制 .htaccess.sample 为 .htaccess 后生效（实测回显 116:$config['index_page'] = '';）。官方 Wiki 给出的对照：

• uri_protocol：框架取路由的方式，REQUEST_URI 是 Apache 下的实测默认，nginx 场景也适用，勿轻易改。
• app_name：浏览器标题与站点名，随意改；app_version 是文件内静态常量，实测值为 2.4.5——它滞后于真实版本，版本核验以 Debug 页 Version（实测 2.8.21）为准。
• directory：Cloudlog 部署在域名子路径时填子路径（如 /cloudlog），实测根路径部署为空串。

5.2 Callbook 呼号查询参数

录入 QSO 时自动补全对方呼号资料的服务配置：

$config['callbook'] = "hamqth"; // Options are hamqth or qrz
$config['qrz_username'] = "";
$config['qrz_password'] = "";
$config['use_fullname'] = false;
$config['hamqth_username'] = "";
$config['hamqth_password'] = "";

• callbook：二选一，hamqth（免费注册即用）或 qrz（完整资料需 QRZ 订阅）。实测默认 hamqth。
• 账号密码：填入对应服务的账户；实测示例值落 admin 类演示账号之外的第三方凭据时，建议生产环境以受控方式注入，不在代码库明文扩散。
• use_fullname：日志中显示全名而非呼号，按需开。

⚠️ 注意：Callbook 账号是「查询用」身份，与 LoTW/Club Log 的上传身份不同——上传凭据配置在台站位置（Station Location）里，别填混。

5.3 台站与显示参数

$config['locator'] = "IO91JS";
$config['table_name'] = "TABLE_HRD_CONTACTS_V01";
$config['display_freq'] = false;

• locator：全局默认网格坐标，距离/方位角计算基准；向导 Default gridsquare 字段写入的就是它。填错只会影响距离统计，改后立即生效。
• table_name：日志主表名，沿 HRD Logbook 表结构约定。已装数据后不要改名（改名等于换表，旧数据全部「消失」）。
• display_freq：未登录访客是否可见频率，公开部署且介意暴露活动规律时保持 false（实测默认）。

cloudlog.php 的显示三件套（实测原值）：

$config['show_time'] = FALSE;
$config['measurement_base'] = 'M';
$config['qso_date_format'] = "d/m/y";

• show_time：官方 Wiki 说明它控制未登录用户能否看到 QSO 时间（默认 false）。公开分享日志又不想暴露操作规律时保持关闭。
• measurement_base：距离单位，M 英里 / K 千米 / N 海里三选一，统计页与距离列即时生效。国内用户建议改 K。
• qso_date_format：PHP date() 格式串，实测默认 d/m/y（英式日月年），可改 Y-m-d 获得 ISO 风格。
• map_gridsquares / map_6digit_grids：地图网格显示开关与 6 位精深网格（更密、计算更重），实测均 FALSE，按需开。
• callsign_tags：日志条目的呼号标签开关，实测 TRUE，一般不动。

5.4 认证与用户体系参数

$config['use_auth'] = true;
$config['auth_table'] = "users";
$config['auth_mode'] = "3";
$config['auth_level'][3] = "Operator";
$config['auth_level'][99] = "Administrator";

• use_auth：启用 Cloudlog 内置用户体系。实测 true——关闭即完全公开（单台站私人用途才考虑），多用户部署必须保持开启。
• auth_mode/auth_table：CodeIgniter 认证库的接表方式，指向 users 表模式 3，与后台 User Accounts 功能绑定，不动。
• auth_level：两级权限映射——3 操作员、99 管理员。后台建用户时选的「角色」即这两个级别；需要只读访客角色时在此扩展（如 [2] => Viewer），但官方未承诺低级别的完整兼容，谨慎自定义。

5.5 会话与 Cookie 参数

$config['encryption_key'] = '3e8fa4d0a8f6d5...'; // 向导生成的 64 位十六进制串
$config['sess_driver'] = 'files';
$config['sess_cookie_name'] = 'ci_cloudlog';
$config['sess_expiration'] = 0;
$config['sess_save_path'] = $cloudlog_session_path;
$config['sess_match_ip'] = FALSE;
$config['sess_time_to_update'] = 300;
$config['sess_regenerate_destroy'] = FALSE;
$config['cookie_prefix']	= '';
$config['cookie_domain']	= '';
$config['cookie_path']		= '/';
$config['cookie_secure']	= FALSE;
$config['cookie_httponly'] 	= FALSE;

• encryption_key：安装向导随机生成（实测形态为 64 位十六进制），会话数据完整性依赖它；更换会使全体在线会话失效，无安全事件不要动。
• sess_driver/sess_save_path：文件驱动，实测会话目录为 /tmp/cloudlog_<40位指纹>_sessions（Debug 页 Session Save Path 实测可见）。该目录在系统临时区，系统重装或整机迁移场景需注意会话不持久属正常。
• sess_expiration：0 表示会话随浏览器关闭结束；希望「记住登录」场景可设为秒数（如 7200）。
• cookie_secure：实测 FALSE（HTTP 部署形态）。上 HTTPS 后改为 TRUE（安装篇 7.3），登录 Cookie 将仅随 HTTPS 请求发送。
• cookie_httponly：实测 FALSE，即脚本可读 Cookie；从安全基线出发建议改 TRUE，减少 XSS 可触达面。
• sess_time_to_update：会话 ID 轮换周期，实测 300 秒，默认即可。

5.6 安全相关参数

$config['global_xss_filtering'] = FALSE;
$config['csrf_protection'] = FALSE;
$config['csrf_token_name'] = 'csrf_test_name';
$config['csrf_cookie_name'] = 'csrf_cookie_name';
$config['csrf_expire'] = 7200;
$config['csrf_regenerate'] = TRUE;
$config['permitted_uri_chars'] = 'a-z 0-9~%.:_\-';
$config['proxy_ips'] = '';

• csrf_protection：实测 FALSE——Cloudlog 自带大量 cron/外部 curl 直调端点（LoTW、备份 API 等），全局 CSRF 会破坏这类免登录端点链路，官方默认保持关闭属于权衡结果；若开启需自行验证所有 cron 端点仍可用。
• global_xss_filtering：框架级输入过滤，默认关（性能考虑）；站点在公网时可通过 Web 层（Apache/反代 WAF）补偿。
• permitted_uri_chars：URI 白名单字符集，实测含空格与连字符——呼号中的 /（如便携操作呼号 VK2/M0ABC）由路由层另行处理，扩展字符集前先想清楚。
• proxy_ips：反代部署时填代理 IP 列表，让框架取真实客户端 IP；直连部署留空（实测值）。

5.7 日志与调试参数

$config['log_threshold'] = 0;
$config['log_path'] = '';
$config['log_file_extension'] = '';
$config['log_file_permissions'] = 0644;
$config['log_date_format'] = 'Y-m-d H:i:s';
$config['compress_output'] = FALSE;
$config['time_reference'] = 'UTC';
date_default_timezone_set ( $config['time_reference'] );

• log_threshold：实测 0（关框架日志）。排障时可临时改 1（错误）或 2（调试），日志落 application/logs/（该目录 4.6 已给 www-data 组写位）；改回 0 免磁盘膨胀。
• log_path：留空即默认 application/logs/。
• time_reference：服务端时间基准 UTC（实测），页面显示时区由 PHP date.timezone（实测 Asia/Shanghai）与用户偏好叠加，两处概念不要混淆——库里存 UTC、显示按本地。
• compress_output：输出压缩，实测关；Apache 已有 mod_deflate 场景不必开。

5.8 数据目录与多语言参数

$config['datadir'] = null; // default to install directory
$config['cl_multilanguage']=true;
$config['composer_autoload'] = FALSE;

• datadir：参考数据目录重定向。实测 null——国家文件（cty.xml）、LoTW 用户 CSV、SCP 文件都落在安装目录的 updates/ 下；多站点共享一份参考数据（或要把大文件挪到独立分区）时设为绝对路径，Update 控制器的取文件逻辑会自动前缀该目录（实测源码中 make_update_path() 先拼 updates/ 再叠加 datadir）。
• cl_multilanguage：多用户语言支持，实测 true；后台 Maintenance 页实测回显 "You have enabled Multuser-Language support"，关闭后 Maintenance 的 Settings 检查项会相应变化。
• composer_autoload：实测 FALSE（Cloudlog 自管依赖，无需 Composer 运行时加载）。

5.9 数据库连接参数（database.php）

实测生效的关键项：

'hostname' => 'localhost',
'username' => 'cloudlog',
'database' => 'cloudlog',
'dbdriver' => 'mysqli',
'dbprefix' => '',

• 四件套与安装向导输入一一对应；dbprefix 留空（Cloudlog 自管表名，前缀机制未用）。
• 换库/迁移时改 hostname 为远端地址并同步 MariaDB 授权（'cloudlog'@'%' 或指定网段），改完 systemctl reload apache2 并刷新站点验证。
• Debug 页 Database Information 区实测回显 Database Name cloudlog、Table Name TABLE_HRD_CONTACTS_V01、Character Set utf8mb4、Collation utf8mb4_general_ci——与 5.3 的 table_name 及建库语句的字符集联动核对。

5.10 Global Options 后台全局选项

后台 Admin → Global Options（路由 /index.php/options）是免改文件的运营层，实测页面六大分类与两个公开开关如下，每类点 Configure 进入：

• 页面顶部另有 Public Station Diary 与 Public Map Confirmations 两个全局公开性开关（实测默认 Public Station Diary 开启，对应 cloudlog.php 的 public_station_diary_enabled = TRUE）。
• 后台项的优先级：用户级设置 > Global Options > 配置文件默认值——同一功能在用户偏好里设置了就以后者为准（官方 Wiki 以主题为例说明此覆盖关系）。

5.11 PHP 运行时参数（php.ini）

Cloudlog 的导入/同步体验高度依赖 Web 侧 PHP 设置，实测值与作用：

以上六项在 Debug 页 PHP Settings 区逐项实测回显一致。修改流程：编辑 /etc/php/8.5/apache2/php.ini → systemctl reload apache2 → Debug 页核对。CLI 与 Web 各有一份 php.ini，只改 Web 份。

六、生产配置模板

以下模板面向「2 核 4GB 内存、40GB 磁盘、个人/俱乐部单机部署、PHP 8.5 + Apache mod_php」场景，差异项逐条给出（其余保持安装默认即可）：

// application/config/config.php —— 生产差异项
$config['base_url'] = 'https://log.example.com';        // 站点根，HTTPS 域名
$config['index_page'] = '';                              // 配合 mod_rewrite 隐藏 index.php
$config['callbook'] = "qrz";                             // 有 QRZ 订阅时切换
$config['cookie_secure'] = TRUE;                         // HTTPS 后必须
$config['cookie_httponly'] = TRUE;                       // XSS 缓解基线
$config['log_threshold'] = 1;                            // 生产留错误日志，落 application/logs/
$config['proxy_ips'] = '192.168.1.10';                   // 若前挂反代，填代理 IP

// application/config/cloudlog.php —— 生产差异项
$config['measurement_base'] = 'K';                       // 千米
$config['qso_date_format'] = "Y-m-d";                    // ISO 风格日期
$config['public_search'] = FALSE;                        // 公开部署保持关闭

; /etc/php/8.5/apache2/php.ini —— 生产差异项
memory_limit = 256M
upload_max_filesize = 32M
post_max_size = 40M
max_execution_time = 300
allow_url_fopen = On

# 应用模板后的生效验证
chown root:www-data /var/www/cloudlog/application/config/config.php /var/www/cloudlog/application/config/cloudlog.php
chmod 640 /var/www/cloudlog/application/config/config.php /var/www/cloudlog/application/config/cloudlog.php
systemctl reload apache2

模板解读：资源参数（256M/32M/40M/300s）与实测环境一致，可支撑数万条 QSO 的 ADIF 批量导入；cookie_secure/cookie_httponly 是 HTTPS 部署的安全底线；log_threshold=1 满足「出错有据可查」而不膨胀磁盘。数据库不在此模板内——单机部署保持 localhost，仅当库与应用分离时改 database.php。

七、常见问题（FAQ）

Q1：改了 php.ini 为什么 Debug 页数值没变？ 改到 CLI 那份了。php --ini 显示的是命令行配置，Apache mod_php 读 /etc/php/8.5/apache2/php.ini；改对文件后还需 systemctl reload apache2，再回 Debug 页核对。

Q2：换域名/上 HTTPS 后站内链接仍跳旧地址？ base_url 未同步。改 config.php 的 base_url 为新地址（HTTPS 站点同时设 cookie_secure = TRUE），reload 后清浏览器缓存重登。

Q3：URL 里想去掉 index.php 但去掉后 404？ 两处必须同时到位：.htaccess.sample 已复制为 .htaccess（Apache AllowOverride All 生效范围内）且 index_page 设空串；404 说明 rewrite 规则未生效，回查安装篇 4.7 的站点配置。

Q4：修改会话目录/encryption_key 后全员掉线？ 预期行为——更换 encryption_key 使既有会话数据无法解密、全部会话失效。仅在密钥疑似泄露时更换，平时不动。

Q5：参考数据想放到独立分区，怎么改？ config.php 设 $config['datadir'] = '/data/cloudlog';，并把 updates/ 下的既有文件（cty.xml、lotw_users.csv、clublog_scp.txt、masterscp.txt）迁移过去，目录属主保持 root:www-data 组可写，再到 Admin → Update Country Files 重跑一次验证。

Q6：后台 Global Options 改了主题，某用户说没生效？ 用户级偏好优先于全局设置（官方 Wiki 明确的覆盖规则）。让该用户在个人 Account 里改回，或清其用户级偏好。

Q7：csrf_protection 能不能开？ 默认关是官方权衡（cron/外部 curl 直调端点依赖免 CSRF 的访问）。开启前逐个验证 LoTW 上传、备份 API、Club Log 同步等端点仍可由 crontab 触发，否则定时任务会静默失败。

Q8：Debug 页显示的版本号与 config.php 里 app_version 不一致？ app_version 是文件内静态常量（实测 2.4.5，滞后），真实版本以 Debug 页 Version（实测 2.8.21）与 git describe --tags 为准，勿按 app_version 排障。

八、参考链接

• 官方 Wiki：Cloudlog.php Configuration File（cloudlog.php 参数的官方说明）：https://github.com/magicbug/Cloudlog/wiki/Cloudlog.php-Configuration-File
• 官方 Wiki：Global Options（后台全局选项官方说明）：https://github.com/magicbug/Cloudlog/wiki/Global-Options
• 官方 Wiki：Debug（Debug 页与环境要求）：https://github.com/magicbug/Cloudlog/wiki/Debug
• 官方 Wiki：Installation（PHP 版本与 php.ini 要求）：https://github.com/magicbug/Cloudlog/wiki/Installation
• 同专栏部署篇（三份配置文件的生成过程）：《Ubuntu 22.04 安装 Cloudlog 指南》
• 同专栏认知篇：《Cloudlog 介绍与选型指南》
• CodeIgniter 3 配置手册（框架层参数的原理依据）：https://codeigniter.com/user_guide/libraries/config.html