Cloudlog 2.8.21 常用命令与运维排障详解

目标：把 Cloudlog 2.8.21 的日常运维收敛成可执行的命令手册——每日升级脚本与定时任务全表、DXCC 国家文件与 LoTW 用户数据的加载与排障实测、备份与恢复、版本升级与回滚、Debug 排障页逐项解读。全部命令与回显在 Ubuntu 22.04 + Apache 2.4.52 + PHP 8.5.12 + MariaDB 10.6.23 实测环境跑通，DXCC/LoTW 两条排障实录为本篇核心沉淀。

一、环境信息

• 部署形态：Ubuntu 22.04 + Apache 2.4.52（mod_php）+ PHP 8.5.12 + MariaDB 10.6.23，Cloudlog 2.8.21 装于 /var/www/cloudlog
• 后台演示账号：admin / q1w2e3r4（站点呼号 M0ABC）
• 运维相关目录实测状态：backup/、updates/、uploads/ 均为 root:www-data 属主、组可写（Debug 页三目录 Success）
• 参考数据实测基线：DXCC 三表 402/31730/4123 行（entities/exceptions/prefixes），LoTW 用户 CSV 6,347,326 字节、237,085 行，Club Log SCP 文件 clublog_scp.txt 1,329,100 字节、master.scp 228,188 字节
• 关联阅读：部署过程见同专栏安装篇 《Ubuntu 22.04 安装 Cloudlog 指南》，参数语义见 《Cloudlog 2.8.21 配置参数详解》

二、运维工具概览

Cloudlog 是纯 Web 应用，没有自带 CLI，日常运维走四类入口，先建立全景：

💡 技术拓展：Web 应用的后台任务驱动有常驻进程、消息队列与「HTTP 端点 + 系统 cron」三种主流形态。常驻进程（如 Laravel queue worker）实时性好但多一个守护对象；消息队列吞吐强但引入中间件；Cloudlog 选择第三种——每个任务就是一个可 curl 的 URL，运维责任收敛到一页 crontab，零额外组件。本文即按该形态展开，代价是任务无内建重试与告警，需靠 cron 记录与端点状态页（4.3 的 status 机制）兜底。

三、前置条件

• 登录态：后台页面操作需管理员账号登录（本章演示 admin）。
• 出网能力：参考数据更新需要服务器能访问 Club Log CDN（cdn.clublog.org）与 ARRL（lotw.arrl.org）——这是本篇排障实录的起因，服务器出网受阻时的替代流程见 4.3 的实录。
• 目录写权限：updates/、backup/ 的组写位在位（安装篇 4.6 落实），端点写入才不会失败。
• API Key（第五章备份自动化需要）：后台 API Keys 页创建一个 Key 并记下。
• crontab 权限：crontab -e 以 root 身份编辑（升级脚本要 git pull 写代码树）。

四、定时任务与参考数据端点详解

4.1 每日升级脚本 cloudlog.sh

官方 Wiki 推荐把「升级 + 权限修正 + 迁移触发」封装成脚本放每日 cron。保存为 /usr/local/sbin/cloudlog.sh（实测环境验证过等价操作序列）：

#!/bin/bash
CLOUDLOG=/var/www/cloudlog
URL=https://log.example.com

cd "$CLOUDLOG" || exit 1
git pull

# git pull 可能以 root 新建文件，重新修正运行目录权限
chown -R root:www-data "$CLOUDLOG"
install -d -o root -g www-data -m 2775 \
  "$CLOUDLOG/application/config" "$CLOUDLOG/application/logs" \
  "$CLOUDLOG/application/cache" "$CLOUDLOG/application/plugins" \
  "$CLOUDLOG/backup" "$CLOUDLOG/updates" "$CLOUDLOG/uploads" \
  "$CLOUDLOG/images/eqsl_card_images" "$CLOUDLOG/assets/qslcard" \
  "$CLOUDLOG/assets/json" "$CLOUDLOG/assets/sstvimages"

# 数据库密码所在的两份配置只留 root 可写、组可读
chmod 640 "$CLOUDLOG/application/config/config.php" \
          "$CLOUDLOG/application/config/database.php"

# 任意页面加载即自动执行数据库迁移，拉完代码触发一次
curl --silent "$URL/index.php/user/login" >/dev/null 2>&1 || true

脚本要点：git pull 拉新代码；install -d -m 2775 一条命令恢复 11 个运行目录的属主与组写位（等价于安装篇 4.6 的权限动作，实测输出 drwxrwsr-x root www-data）；chmod 640 收紧两份含数据库密码的配置；最后 curl 一次登录页触发迁移。启用：

chmod 700 /usr/local/sbin/cloudlog.sh
/usr/local/sbin/cloudlog.sh

⚠️ 注意：若 git pull 报目录所有权保护错误，以执行脚本的同一账户跑一次 git config --global --add safe.directory /var/www/cloudlog（安装篇 FAQ 8 同源问题）。

4.2 推荐定时任务全表

官方 Wiki「Recommended Cron Jobs」给出推荐节奏（未配置的第三方服务对应行直接跳过）。crontab -e 后按需添加（域名替换为实际站点）：

# 每日 0 点升级 Cloudlog（4.1 脚本）
0 0 * * * /bin/bash -c "/usr/local/sbin/cloudlog.sh"

# Club Log 上传（需账号配置且台站位置开启 Upload to Clublog）
3 */6 * * * curl --silent https://log.example.com/index.php/clublog/upload &>/dev/null

# LoTW 上传（需台站位置上传证书；同时下载对账 QSO）
0 */1 * * * curl --silent https://log.example.com/index.php/lotw/lotw_upload &>/dev/null

# QRZ Logbook 上传 / 下载（需 API Key）
6 */6 * * * curl --silent https://log.example.com/index.php/qrz/upload &>/dev/null
18 */6 * * * curl --silent https://log.example.com/index.php/qrz/download &>/dev/null

# HRDLog 上传
12 */6 * * * curl --silent https://log.example.com/index.php/hrdlog/upload &>/dev/null

# eQSL 收发同步
9 */6 * * * curl --silent https://log.example.com/index.php/eqsl/sync &>/dev/null

# LoTW 活跃用户清单（ARRL 每周日约 1000z 更新，每周拉一次足够）
10 1 * * 1 curl --silent https://log.example.com/index.php/update/lotw_users &>/dev/null

# Club Log SCP 呼号库
@weekly curl --silent https://log.example.com/index.php/update/update_clublog_scp &>/dev/null

# DOK / SOTA / WWFF / POTA 参考文件（更新缓慢，月更即可）
@monthly curl --silent https://log.example.com/index.php/update/update_dok &>/dev/null
@monthly curl --silent https://log.example.com/index.php/update/update_sota &>/dev/null
@monthly curl --silent https://log.example.com/index.php/update/update_wwff &>/dev/null
@monthly curl --silent https://log.example.com/index.php/update/update_pota &>/dev/null

# 插件 cron 钩子（无启用插件可跳过）
0 * * * * curl --silent https://log.example.com/index.php/plugins/cron &>/dev/null

解读：同步类（Club Log/QRZ/HRDLog/eQSL）每 6 小时是官方建议上限节奏——这些端点走的不是对方实时 API，打得太勤没有收益；参考数据类（LoTW 用户/SCP/DOK/SOTA/WWFF/POTA）按数据源更新频率定周/月节奏即可。

4.3 DXCC 国家文件更新（排障实录）

DXCC 判定数据由 Club Log 提供，更新链路是：Update 控制器从 https://cdn.clublog.org/cty.php?api=a11c3235cd74b88212ce726857056939d52372bd 下载 gzip 压缩包（该 API 串为 Cloudlog 开源代码内置），失败自动回退 https://cdn.cloudlog.org/clublogxml.gz；下载后解压写 updates/cty.xml，清空 dxcc_entities/dxcc_exceptions/dxcc_prefixes 三表重灌，进度写入 updates/status.html。

后台入口（Admin → Update Country Files，实测页面结构）：

Updates
DXCC Lookup Data
Distance Data
Here you can update the DXCC lookup data that is used for displaying callsign information.
This data is provided by Clublog.
[Check for DXCC Data Updates]  [Update DXCC Data]
Status:
Ready to update
Apply DXCC Data to Logbook
[Check QSOs missing DXCC data]  [Re-check all QSOs in logbook]
Apply Continent Data to Logbook
[Check QSOs missing continent data]
Update distance data

更新进行中/完成态由端点轮询呈现，直接 curl 状态端点即得（实测回显，完成后）：

curl -s http://127.0.0.1/index.php/update/get_status

DONE<br/>Dxcc Entities: 402<br/>Dxcc Exceptions: 31730<br/>Dxcc Prefixes: 4123<br/>

排障实录：状态页 0 字节 / 更新卡死。实测环境曾出现「国家文件更新页拉取失败（响应 0 字节）」：服务器无法直连外网，update/dxcc 下载阶段挂起。定位过程与处置：

1. 确认根因——在服务器上探测出网（实测 curl -m 8 探 Club Log 域名返回连接失败），判定为下载阶段阻塞而非应用故障；

2. 替代加载——先在能出网的机器取回数据包（实测走代理下载 cty.php?api=... 得 676,424 字节 gzip 包，file 识别为 gzip compressed data, was "cty.xml" ... original size 10204266），解压为 cty.xml 放入 updates/ 并修正属主（chown root:www-data、组可写），再依次调用只读本地文件的导入端点完成三表灌库：

   cd /var/www/cloudlog/updates && gzip -d -f clublogxml.gz
   chown root:www-data cty.xml && chmod 664 cty.xml
   curl -s http://127.0.0.1/index.php/update/dxcc_entities
   curl -s http://127.0.0.1/index.php/update/dxcc_exceptions
   curl -s http://127.0.0.1/index.php/update/dxcc_prefixes
   

3. 验证——数据库行数与状态页双核对（实测回显）：

   mariadb cloudlog -e 'SELECT COUNT(*) AS entities FROM dxcc_entities; SELECT COUNT(*) AS exceptions FROM dxcc_exceptions; SELECT COUNT(*) AS prefixes FROM dxcc_prefixes;'
   

   entities
   402
   exceptions
   31730
   prefixes
   4123
   

   updates/status.html 与 get_status 端点同步显示 DONE（见上文回显），Dashboard 的 Countries Breakdown 出现 Needed 340，DXCC 判定即告生效。

⚠️ 注意：dxcc_entities 等三个子端点只灌库不清表，重复调用会重复插行；需要重灌时用页面的 Update DXCC Data（走 update/dxcc，先清空三表再灌）或先手动 TRUNCATE。生产服务器能直连 Club Log CDN 时不需要上述替代流程，直接点页面按钮即可。

4.4 LoTW 用户数据加载（排障实录）

LoTW 活跃用户清单来自 ARRL：https://lotw.arrl.org/lotw-user-activity.csv。数据分两层落地——文件层（updates/lotw_users.csv，端点 index.php/lotw/load_users 或 index.php/update/download_lotw_users 下载，成功输出 LoTW User Data Saved.）与数据库层（lotw_users 表，端点 index.php/update/lotw_users 下载并 TRUNCATE 后重灌，去重保留每呼号最新时间戳）。

实测环境出网受阻，采用文件级替代（实测全过程）：

# 在能出网的机器下载 CSV（实测 6,347,326 字节、237,085 行）
curl -sS -x http://192.168.1.72:7897 -o lotw-user-activity.csv https://lotw.arrl.org/lotw-user-activity.csv
head -3 lotw-user-activity.csv
grep -c . lotw-user-activity.csv

1A0C,2026-07-27,15:21:03
1A0KM,2014-02-08,15:08:08
1A3A,2008-09-12,22:44:57
237085

将 CSV 放入 updates/lotw_users.csv（属主 root:www-data）后，文件层消费者立即可用。验证文件层判定（实测踩坑——见下）：

curl -s http://127.0.0.1/index.php/lotw/lotw_usercheck/W1AW
curl -s http://127.0.0.1/index.php/lotw/lotw_usercheck/G4IFX

Not Found
Not Found

W1AW（ARRL 官方电台，实测 CSV 第 4 万余行确有 W1AW,2026-10-20,15:30:21）却返回 Not Found——这是 2.8.21 的真实代码缺陷：Lotw.php 的 lotw_usercheck() 用 fgetcsv 逐行扫描，但 else 分支写了 echo "Not Found"; break;，即只比对第一行就退出循环（实测源码片段，首行为 1A0C，与任何非 1A0C 呼号都不等，恒返回 Not Found）。定位方式：grep -n 'function lotw_usercheck' -A 14 application/controllers/Lotw.php。

处置与结论：

• 该判定函数用于录入界面的 LoTW 用户即时提示，修复方式为去掉 else 分支的 break（等上游版本更新）；判断「呼号是否 LoTW 活跃」的可靠路径是数据库层——运行 index.php/update/lotw_users 端点灌库（出网正常的服务器上由 4.2 的每周 cron 完成），查询 lotw_users 表：

  mariadb cloudlog -e 'SELECT COUNT(*) AS lotw_users FROM lotw_users;'
  

  lotw_users
  0
  

  实测环境数据库层为 0 行（替代流程只覆盖了文件层），生产服务器跑过每周 cron 后该表约 20 万行级，录入判定走数据库即正确。

• 若录入页 LoTW 提示异常，按「CSV 文件在不在 → 数据库行数 → usercheck 已知缺陷」三步排查。

4.5 Maintenance 手动触发与完整性检查

Admin → Maintenance（路由 /index.php/maintenance）把 4.2 的参考数据任务做成了页面按钮，适合装完站后手动逐项初始化。实测页面结构：

Maintenance
QSO-DB Maintenance
Everything ok
Every QSO in your Database is assigned to a station-profile (location)
Settings Maintenance
Everything ok
You have enabled Multuser-Language support
Data File Updates
Manually update reference data files used by Cloudlog. These updates are normally run via cron, but you can trigger them manually here.
Data Source        Description                                  Action
Clublog SCP        Super Check Partial callsign database        [Update Clublog SCP]
LoTW Users         Active Logbook of the World users database   [Update LoTW Users]
DOK                German DOK and SDOK reference data           [Update DOK]
SOTA               Summits on the Air reference data            [Update SOTA]
WWFF               World Wide Flora & Fauna reference data      [Update WWFF]
POTA               Parks on the Air reference data              [Update POTA]

两个检查区即健康基线：QSO-DB Maintenance 检查每条 QSO 都挂有台站位置（实测 Everything ok），Settings Maintenance 检查设置一致性（实测 Everything ok，并回显多语言已启用）。出问题会在此页给出具体 QSO/设置项，按提示修复后刷新复查。

五、备份与恢复命令详解

5.1 应用层备份端点（官方 Wiki 方式）

Cloudlog 自带备份区（后台 Backup 页），可下载全部 ADIF 条目与笔记；自动化复用只读 API Key：后台 API Keys 页创建一个 read-only Key，然后按官方 Wiki 的推荐 cron 每日触发：

# 备份 API Key 关联台站位置的全部 ADIF，每日 0 点
0 0 * * * curl --silent https://log.example.com/index.php/backup/adif/<APIKEY> &>/dev/null
# 备份该 Key 所属用户的笔记
0 0 * * * curl --silent https://log.example.com/index.php/backup/notes/<APIKEY> &>/dev/null

备份产物落 backup/ 目录（ADIF 形如 logbook_年_月_日_时_分_秒.adi，笔记形如 notes_….xml）。要「触发即下载到异地」，官方 Wiki 给出的脚本思路是请求端点后从返回页解析出文件名再 wget 取回；本文实测环境未启用该链路，故仅给端点形态供对照，不杜撰回显。

5.2 数据库级备份（实测）

整库冷备是更彻底的兜底，mariadb-dump 一条命令（实测回显）：

mariadb-dump cloudlog > /var/www/cloudlog/backup/cloudlog-db-$(date +%Y%m%d).sql
ls -lh /var/www/cloudlog/backup/ | tail -3
head -2 /var/www/cloudlog/backup/cloudlog-db-*.sql | tail -1
grep -c 'INSERT INTO' /var/www/cloudlog/backup/cloudlog-db-*.sql

total 3.0M
-rw-r--r-- 1 root www-data 3.0M Oct 30 16:58 cloudlog-db-20261031.sql
-- MariaDB dump 10.19  Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64)
20

空库（20 个建表 INSERT 块、3.0MB）即此形态；随日志量增长文件线性变大。恢复用 mariadb cloudlog < cloudlog-db-YYYYMMDD.sql。建议把该命令并入 4.1 的每日脚本，产物同步异地。恢复演练流程：DROP DATABASE → 重建（字符集 utf8mb4）→ 导入 → 刷新站点验证登录与日志条目数。

5.3 备份清单建议

六、升级与回滚详解

git 方式（推荐）：升级前先备份（第五章），然后执行 4.1 脚本或手动序列：

cd /var/www/cloudlog
git pull
git describe --tags

升级后打开任意页面触发数据库迁移（迁移版本随代码更新，实测 2.8.21 为 286），到 Debug 页核对 Version 已变为新 tag。官方 Wiki 特别提醒：升级过程个别配置文件可能被重置为默认值，升级后对照旧版 application/config/cloudlog.php（该文件不在 git 跟踪范围，pull 不覆盖；重点是核对 config.php 中向导生成的差异项）逐项回填。

zip 方式：下载新版 zip（安装篇 5.1 的下载与校验方法）→ 备份 → 解压覆盖到安装目录（保留 application/config/ 下的生成文件与 updates/、backup/ 数据目录）→ 后续同 git 方式。

回滚：git 部署回滚即 git checkout -q <旧tag> 后刷新站点（迁移版本一般向前兼容，跨大版本回滚前先恢复数据库备份）；zip 部署回滚用旧包重新解压覆盖。任何回滚前先做 5.2 的整库备份。

七、Debug 排障页详解

Admin → Debug Information（路由 /index.php/debug）是排障第一入口，官方 Wiki 定位为「排查用户安装问题的简易工具」。实测页面全量解读（本环境实测值）：

页面右上 Copy as Markdown 按钮可一键复制整份报告，官方设计意图即粘贴到 GitHub Discussions 求助帖——远程求助时先贴它。注意 Web 生效的 php.ini 与 CLI 不同（配置篇 Q1），Debug 页显示的是 Web 实际生效值，以它为准。

八、常见问题（排障实录汇总）

Q1：国家文件更新页 0 字节/更新卡死？ 见 4.3 实录：先探出网（实测根因是服务器无法直连 Club Log CDN，下载阶段阻塞），能出网就重试页面按钮；不能出网就走「外网取包 → 放 updates/cty.xml → 依次调三个导入端点 → 行数+状态页双验证」。注意子端点不清表勿重复调。

Q2：LoTW 用户判定始终 Not Found？ 见 4.4 实录：2.8.21 的 lotw_usercheck() 存在只比对 CSV 首行即退出的代码缺陷，返回值不可信；可靠判定走 lotw_users 数据库表（每周 cron update/lotw_users 灌库）。

Q3：cron 任务跑了但数据没更新？ 三层排查：crontab -l 确认任务在位 → 手动执行同一 curl 命令看输出/HTTP 状态（cron 的 shell 不读你的环境变量，代理类设置必须写进命令行）→ 查 application/logs/ 框架日志（临时把 log_threshold 调到 1）。Apache 访问日志（/var/log/apache2/cloudlog_access.log）能确认请求是否到达。

Q4：升级后页面报错或功能异常？ 先做 5.2 备份，再按第六章流程：确认 git describe --tags 到位 → 打开站点触发迁移 → Debug 页核对 Version/Migration → 对照旧 cloudlog.php 回填被重置的配置项。

Q5：/backup /updates /uploads 在 Debug 页显示不可写？ 组写位丢失（多见于手工解包覆盖后）。重跑安装篇 4.6 的 install -d -o root -g www-data -m 2775 ...（11 个目录一条命令）即可，实测恢复为 drwxrwsr-x。

Q6：导入 ADIF 中途停摆？ 内存/时限瓶颈：调大 Web 侧 php.ini 的 memory_limit、max_execution_time（配置篇 5.11 实测基线 256M/300s）后 reload Apache，回 Debug 页确认生效值再重试导入。

Q7：LoTW 上传报 OpenSSL 相关错误？ Debug 页 PHP Modules 区确认 openssl 为 Installed（本篇实测环境 8 模块全绿）；缺失则补齐 php8.5 包集合并重启 Apache。LoTW 证书签名硬依赖该扩展。

Q8：误删了 updates/cty.xml 或 CSV？ 均可再生：cty.xml 走 4.3 重灌，LoTW CSV 走 4.4 端点重下（或每周 cron），SCP 文件走 Maintenance 页 Update Clublog SCP。参考数据目录里的东西没有不可再生的。

九、参考链接

• 官方 Wiki：Recommended Cron Jobs（4.1/4.2 任务表的源头）：https://github.com/magicbug/Cloudlog/wiki/Recommended-Cron-Jobs
• 官方 Wiki：Backup（备份端点与自动化）：https://github.com/magicbug/Cloudlog/wiki/Backup
• 官方 Wiki：Updating（升级与回滚官方指引）：https://github.com/magicbug/Cloudlog/wiki/Updating
• 官方 Wiki：Debug（排障页说明）：https://github.com/magicbug/Cloudlog/wiki/Debug
• 官方求助论坛：https://github.com/magicbug/Cloudlog/discussions
• 同专栏部署篇：《Ubuntu 22.04 安装 Cloudlog 指南》
• 同专栏配置篇：《Cloudlog 2.8.21 配置参数详解》
• 同平台同类组件运维参考：《MyBB 1.8.41 常用运维命令与排障详解》