WeeWX 常用 CLI 命令与排障详解

目标：覆盖 WeeWX 5.5.2 日常运维的命令行工具箱——核心工具 weectl 的 8 个子命令逐个讲解（动作集、参数、真实回显），配套守护进程 weewxd、systemd 服务管理与 sqlite3 数据库直查，并把安装、驱动切换、配置语法、扩展安装等场景的排障实录沉淀成可复用的排查路径。全部命令与回显均在 Ubuntu 22.04 + WeeWX 5.5.2 实机执行验证。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64），WeeWX 5.5.2（官方发布件安装：DEB 形态与 pip/venv 形态各一套实测环境，命令行为完全一致，仅配置默认路径不同——DEB 为 /etc/weewx/weewx.conf，pip 形态为 <数据区>/weewx.conf，如 /root/weewx-data/weewx.conf）
• 工具版本：weectl 5.5.2、weewxd 5.5.2（--version 实测）
• 验证环境：默认 Simulator 驱动，服务由 systemd 托管，报告输出 /var/www/html/weewx/
• 部分回显来自 pip 形态环境（回显中配置路径显示为 /root/weewx-data/weewx.conf），不影响命令语法与结论
• 排障信息溯源：官方文档 5.5 版 Utilities guide（weewxd / weectl 各页），查询日期 2026-10-31

二、工具概览

WeeWX 5.x 的命令行工具体系由四层组成：

V4 → V5 工具变化（升级用户必读）：V4 时代的 wee_reports、wee_import、wee_database 等散装工具在 V5 全部收编进 weectl。实测 which wee_reports 无任何输出（命令已不存在），其功能由 weectl report run 替代。weewxd 的运行参数也精简为「主程序只管跑，管理全走 weectl」。

weectl 的 8 个子命令（weectl --help 实测）：

{database,debug,device,extension,import,report,rest,station}

💡 技术拓展：weectl 的定位类似 Git 的「上层命令合集」——一个入口 + N 个子命令，每个子命令有独立动作集（如 weectl database 下挂 9 个动作）。同类气象软件里，Cumulus MX 靠 Web 界面管理、Weather-Display 是 GUI 程序，WeeWX 选择纯 CLI 管理面，天然适配 SSH 运维与脚本化巡检，代价是没有「点点鼠标」的后台（配置文件才是唯一事实源）。

三、前置条件

1. 已安装 WeeWX 5.5.2 并能执行 weectl --version（安装见 《Ubuntu 22.04 安装 WeeWX 5.5.2 指南》）；
2. root 或 sudo 权限（部分动作要写 /etc/weewx/、重启服务）；
3. 已安装 sqlite3 客户端（sudo apt install -y sqlite3）；
4. DEB 形态下 weectl 在系统 PATH（/usr/bin/weectl）；pip 形态在 venv 的 bin 下（如 /opt/weewx-venv/bin/weectl）。

四、weectl 全局用法

4.1 版本与子命令清单

weectl --version
weectl --help

实测回显：

weectl 5.5.2

--help 输出的子命令行（节选）：

usage: weectl [-h] [--version]
              {database,debug,device,extension,import,report,rest,station} ...

4.2 三个全局选项

所有子命令共享的参数约定：

排障实录（EOFError）：weectl database 系动作默认会弹「y/n」确认，在无标准输入的环境直接跑会崩：

EOFError: EOF when reading a line

这不是 bug，是确认提示读不到输入。脚本化调用一律补 -y。

4.3 动作帮助的查看姿势

每个子命令的支持动作用 weectl <子命令> --help 查看。例如 weectl database --help 的动作清单（实测）：

{create,drop-daily,rebuild-daily,add-column,rename-column,drop-columns,reconfigure,transfer,calc-missing}

九个动作全部支持 --config、--binding、--dry-run、-y。

五、weectl station：站点与驱动管理

动作集：create（pip 形态新建数据区）/ reconfigure（改站点参数、切驱动）/ upgrade（升级数据区结构）。

5.1 reconfigure 参数表

weectl station reconfigure --help 实测支持的参数：

执行后回显的第一行总是备份确认（实测）：

Saved old configuration file as /etc/weewx/weewx.conf.20261030151326

配置备份副本为 weewx.conf.时间戳 格式，连续操作会留多份（实测同一天内出现 .20261030151326 与 .20261030151403 两份）。回滚 = 把备份文件复制回 weewx.conf。

5.2 改站点元数据

sudo systemctl stop weewx
sudo weectl station reconfigure --location="Beijing Haidian" --latitude=39.9042 --longitude=116.4074 --altitude=44,meter --no-prompt
sudo systemctl start weewx

站点参数改完即生效（报告在下一个归档边界刷新）。注意：站点元数据与单位制在数据库建库时固化，站点级大改后建议删除旧库重建（sudo rm /var/lib/weewx/weewx.sdb），避免模拟器默认数据混入真实数据。

5.3 排障实录：切换驱动后服务反复崩溃

无真实硬件时把驱动切到 Davis Vantage，是一条完整的「工具成功、运行失败」链路：

sudo systemctl stop weewx
sudo weectl station reconfigure --driver=weewx.drivers.vantage --no-prompt
sudo systemctl start weewx

reconfigure 本身成功（Saved old configuration file as ...，且 [Vantage] 段被自动注入）。但启动后服务立刻崩溃，journalctl -u weewx --no-pager | tail -8 实测：

CRITICAL weewx.engine: Import of driver failed: [Errno 2] could not open port /dev/ttyUSB0: [Errno 2] No such file or directory: '/dev/ttyUSB0'
CRITICAL __main__: Unable to load driver weewx.drivers.vantage
    ****  Exiting...

systemd 侧（systemctl status weewx）：

Active: failed (Result: exit-code)
Process: ... (code=exited, status=4/NOPERMISSION)

排查路径：could not open port /dev/ttyUSB0 → 串口设备不存在（ls -l /dev/ttyUSB0 核对；真实硬件场景则查 USB 线、驱动 dmesg | grep tty、用户组权限 dialout）→ 无硬件评估场景直接切回模拟器：

sudo weectl station reconfigure --driver=weewx.drivers.simulator --no-prompt
sudo systemctl restart weewx
systemctl is-active weewx

实测回显：

active

结论：weectl station reconfigure --driver 只改配置不做硬件探测，「切驱动成功」不等于「能跑起来」；无硬件时保留 Simulator 驱动。

六、weectl database：数据库维护

动作集与用途（weectl database --help 实测 + 官方 Utilities guide）：

6.1 calc-missing：补算派生量（dry-run 实测）

weectl database calc-missing --from=2026-10-30 --to=2026-10-30 --dry-run -y

实测回显（全文）：

Using configuration file /root/weewx-data/weewx.conf
This is a dry run. Nothing will actually be done.
Missing derived observations will be calculated from 2026-10-30 00:00:00 UTC (1793318400) through to 2026-10-30 00:00:00 UTC (1793318400) inclusive.
Calculating missing derived observations...
Processing record: 0; Last record: 2026-10-30 00:00:00 UTC (1793318400)
This is a dry run, recalculation of daily summaries was skipped
Missing derived observations calculated in 0.00 seconds
This was a dry run. Nothing was actually done.

dry-run 全程明确标注「Nothing will actually be done」，展示处理区间与记录数后跳过实算。去掉 --dry-run 即真正补算。典型场景：改过 [StdCalibrate]/[StdQC] 配置后，把历史记录中被置 NULL 的派生量补齐。

6.2 rebuild-daily：重建日汇总（实跑）

weectl database rebuild-daily --date=2026-10-30 -y

实测回显：

Using configuration file /root/weewx-data/weewx.conf
Proceeding will destroy the daily summaries for 2026-10-30, and then rebuild them.
Proceed (y/n)? y
Processed 11 records to rebuild 1 daily summary in 0.01 seconds.

11 条归档记录重算 1 天日汇总，0.01 秒完成。日汇总表（archive_day_*）是报告高低值统计的直接数据源，报告数字与原始记录对不上时，rebuild-daily 是第一修复动作。

七、weectl report：报告管理

动作集：{list,run}。

7.1 report list：盘点报告

weectl report list

实测回显：

Using configuration file /root/weewx-data/weewx.conf
Report Name        Skin         Enabled  Units  Language
SeasonsReport      Seasons      Y        US     en
SmartphoneReport   Smartphone   N        US     en
MobileReport       Mobile       N        US     en
StandardReport     Standard     N        US     en
FTP                Ftp          N        US     en
RSYNC              Rsync        N        US     en

六种报告的启用状态、皮肤、单位制、语言一目了然，与 weewx.conf [StdReport] 段的 enable 值一一对应。

7.2 report run：手动生成报告

weectl report run SeasonsReport

实测回显：

Using configuration file /root/weewx-data/weewx.conf
The following reports will be run: SeasonsReport
Generating as of last timestamp in the database.
Done.

默认按库内最新时间戳生成。V5 还支持补生成历史时刻（实测）：

weectl report run SeasonsReport --date=2026-10-30 --time=15:10

实测回显：

Using configuration file /root/weewx-data/weewx.conf
The following reports will be run: SeasonsReport
Generating for requested time 2026-10-30 15:10:00 UTC (1793373000)
Done.

--date/--time 让报告按指定时刻的数据状态渲染（时区按服务器时区解释，回显标注 UTC）。这一能力替代了 V4 的 wee_reports 工具（实测 which wee_reports 无输出，已随 V5 移除）。

排障关联：report run 报 Generator terminated 时九成是 HTML_ROOT 权限问题（weewxd 以 weewx 用户运行，输出目录须 chown weewx:weewx），完整实录见 《WeeWX 5.5.2 配置参数详解》 5.5 节。

八、weectl rest：上传服务管理

动作集：{list,run}。

8.1 rest list：盘点上传服务

weectl rest list

实测回显：

Using configuration file /root/weewx-data/weewx.conf
Service Name       Target             Enabled  Last Good
StationRegistry    weewx.com          N        N/A
Wunderground       wunderground.com   N        N/A
PWSweather         pwsweather.com     N        N/A
CWOP               cwop.aprs.net      N        N/A
WOW                wow.metoffice.gov  N        N/A
WOW-BE             wow.meteo.be       N        N/A
AWEKAS             www.awekas.at      N        N/A

七个内置上传目标全部列出，默认全关（Enabled=N，与启动日志逐条 Posting not enabled. 一致）。

8.2 rest run：强制上传

weectl rest run Wunderground

实测回显：

Using configuration file /root/weewx-data/weewx.conf
Uploading record for 2026-10-30 16:15:00 UTC (1793376900)
Wunderground: not enabled; skipping.
Done.

rest run 把库内最新归档记录推给指定服务，用于配置好凭据后立即验证连通性（不必等下一个归档边界）。未启用时明确报 not enabled; skipping.——上传排障先看这一行：要么 [StdRESTful][[Wunderground]] enable = true 没改，要么改完没重启。

九、weectl extension：扩展管理

动作集：{list,install,uninstall}；install/uninstall 支持 --dry-run、--yes、--verbosity=N。

9.1 extension list 与安装来源

weectl extension list

实测回显：

Using configuration file /root/weewx-data/weewx.conf
No extensions installed.

install 接受三种来源（weectl extension --help 实测）：

install             Install an extension contained in FILE (such as
                    pmon.tar.gz), directory (DIR), or from an URL.

即：作者打包的 tar.gz（推荐）、解开的目录、或 URL。

9.2 排障实录：三种安装来源的实际结果

扩展安装是「来源敏感」的，实测三种来源：

1. GitHub 仓库 URL（https://github.com/matthewwall/weewx-pmon）→ 失败：请求返回 Not Found（9 字节响应体）。WeeWX 扩展发布件不是仓库本身，裸仓库 URL 不是合法扩展包；
2. 老版本发布链接（lancet.mit.edu 上的历史 tar.gz）→ 失败：返回 276 字节的 HTML 错误页，链接已失效；
3. 作者打包的 tar.gz 本地文件 → 成功安装路径（weectl extension install pmon.tar.gz）。

结论：装扩展认准扩展作者发布的 tar.gz 包（官方 Wiki 各扩展页给出下载地址），仓库 URL 与历史链接不可靠。安装前先 --dry-run 看动作清单；安装完成后扩展落位 bin/user/ 并在 [Engine] 服务链注册，weectl extension list 复查。

十、weectl device、import、debug：辅助三件套

10.1 weectl device：驱动配置工具

weectl device

实测回显（Simulator 驱动）：

Using configuration file /root/weewx-data/weewx.conf
Using driver weewx.drivers.simulator.
The driver weewx.drivers.simulator does not include a configuration tool.

weectl device 调用当前驱动的「配置工具」——真实硬件驱动（如 Vantage）用它读/写主机上的EEPROM 参数（归档间隔、经纬度等），纯软件驱动（Simulator）没有配置工具，如实报告。排障用途：确认「当前生效的驱动到底是谁」——输出的 Using driver ... 行即配置里 station_type 解析后的真实驱动。

10.2 weectl import：历史数据导入

weectl import --help 实测要点：--import-config 必带（指定导入配置文件，声明源格式与字段映射），时间范围参数 --date / --from / --to，行为参数 --update / --dry-run / --no-prompt。内置源格式覆盖 CSV、Weather Underground 历史记录、Cumulus、WeatherDisplay、WeatherCat 五类（官方 Utilities guide / weectl import）。从其他气象软件迁移时用，常规运维不碰；导入永远先 --dry-run。

10.3 weectl debug：诊断信息一键打包

weectl debug --output=weewx-debug.txt

实测输出文件内容结构（节选）：

System info:
    Platform: ...
    Python Version: ...
Load Information:
    1 minute: 0.05
    5 minute: 0.12
    15 minute: 0.09
General Weewx info:
    Weewx version 5.5.2 detected.

文件后半段是「parsed and obfuscated copy of weewx.conf」（配置的解析+脱敏副本）。官方说明：发论坛/邮件求助时附上这个文件即可，密码、用户名、API Key 会被混淆——但官方同时提醒发布前仍应自行通读一遍确认无敏感信息。

十一、weewxd 与 systemd 服务运维

11.1 weewxd 直接运行

weewxd --help 实测参数集：

生产由 systemd 托管，weewxd 手工运行主要用于前台调试——日志直接打到终端，Ctrl-C 退出。--exit 可当配置体检用：能走到退出说明配置解析无误。

11.2 systemd 服务管理（DEB 形态标准五连）

systemctl status weewx        # 状态（active/failed、PID、内存）
systemctl start weewx         # 启动
systemctl stop weewx          # 停止
systemctl restart weewx       # 重启（改配置后必做）
systemctl is-active weewx     # 脚本化探活，输出 active/failed

单元要点（systemctl cat weewx 实测）：User=weewx（低权运行）、ExecStart=/usr/share/weewx/weewxd /etc/weewx/weewx.conf、Requires=time-sync.target（时钟先就绪）、StandardError=journal+console（日志进 journald）。

11.3 journalctl 日志排查组合

journalctl -u weewx --no-pager | tail -30     # 最近 30 行
journalctl -u weewx --since "10 min ago"      # 时间窗过滤
journalctl -u weewx -p err --no-pager         # 只看 err 及以上

启动日志是配置的「自述书」，每次重启完整打印运行环境。健康启动的结尾三行（实测）：

INFO weewx.manager: Starting backfill of daily summaries
INFO weewx.manager: Empty database
INFO weewx.engine: Starting main packet loop.

看到 Starting main packet loop. 才算真正跑起来。

11.4 排障速查表（实测沉淀）

十二、sqlite3 数据库直查

工具链之外，sqlite3 是终审手段——一切命令报「成功」后，落没落库它说了算。

sqlite3 /var/lib/weewx/weewx.sdb '.tables'

实测回显（节选，日汇总表按观测类型一表一个）：

archive                                archive_day_lightning_disturber_count
archive_day_ET                         archive_day_lightning_energy
archive_day_UV                         archive_day_lightning_noise_count
archive_day_appTemp                    archive_day_barometer

归档主表结构（PRAGMA table_info(archive); 实测节选）：

0|dateTime|INTEGER|1||1
1|usUnits|INTEGER|1||0
2|interval|INTEGER|1||0
3|altimeter|REAL|0||0
4|appTemp|REAL|0||0
5|barometer|REAL|0||0

dateTime 是 Unix 时间戳主键，usUnits 标记记录单位制。常用核对查询：

sqlite3 /var/lib/weewx/weewx.sdb "SELECT COUNT(*) FROM archive;"
sqlite3 /var/lib/weewx/weewx.sdb "SELECT datetime(dateTime,'unixepoch'), outTemp, barometer FROM archive ORDER BY dateTime DESC LIMIT 3;"

排障妙用：配置实验用「换库名」隔离（[Databases] 的 database_name 改名即得全新库，实测旧库原样保留），验证后删实验库回滚，不动生产数据。

十三、注意事项

1. 改配置 → restart → 看日志是所有配置类命令的铁三角；weectl 系列只改文件，不触碰运行中的进程；
2. 非交互环境必带 -y：database/extension 的破坏性动作有交互确认，脚本里漏 -y 直接 EOFError；
3. 破坏性动作先 --dry-run：rebuild-daily（销毁重算日汇总）、transfer（整库迁移）、extension install 都支持演算；
4. pip 形态记得 --config：多数据区机器上不指定配置时，weectl 用的默认路径可能不是你以为的那个（回显第一行 Using configuration file ... 每次都要核对）；
5. 配置备份即回滚点：weectl station reconfigure 自动存 weewx.conf.时间戳，别随手清；
6. 命令行收尾核对：管理类命令完成后用 weectl report list / weectl rest list / weectl extension list 三个 list 复查状态，比翻配置文件快。

十四、常见问题

Q1：weectl 显示的配置路径和我的不一样？ weectl 按「--config 参数 → 环境推断 → 默认路径」取配置。pip 形态默认在数据区（如 /root/weewx-data/weewx.conf），DEB 形态在 /etc/weewx/weewx.conf。每条命令回显第一行的 Using configuration file ... 就是本次实际用的文件。

Q2：wee_reports / wee_database 找不到命令？ V5 已移除，分别由 weectl report run 与 weectl database 替代（V4→V5 工具对照见第二节）。

Q3：reconfigure 之后服务起不来，报 SerialException？ 驱动切到了真实硬件驱动而硬件不可达（串口不存在/无权限）。这不是 reconfigure 失败——它只改配置。处理见 5.3 节实录：核对 /dev/ttyUSB* 存在性与 dialout 组，或切回 Simulator。

Q4：脚本里跑 weectl database 卡死或报 EOFError？ 交互确认读不到标准输入。补 -y（或先 --dry-run 演算再实跑）。

Q5：如何验证配置文件语法是否正确（不重启服务）？ weewxd --exit --config=/etc/weewx/weewx.conf：配置解析通过则正常退出，语法错误会打出 configobj.ParseError 及行号，与启动失败时同源。

Q6：报告想按历史某个时刻重新生成？ weectl report run <报告名> --date=YYYY-mm-dd --time=HH:MM（实测见 7.2），替代 V4 的 wee_reports。

Q7：扩展从 GitHub 仓库 URL 装不上？ 扩展发布件是作者打包的 tar.gz，不是仓库本身。从官方 Wiki 扩展页拿 tar.gz 链接，下载后 weectl extension install <文件>（见 9.2 实录）。

十五、参考链接

• 官方 Utilities guide / weectl 总览：https://weewx.com/docs/5.5/utilities/weectl-about/（查询日期 2026-10-31）
• 官方 Utilities guide / weectl station：https://weewx.com/docs/5.5/utilities/weectl-station/
• 官方 Utilities guide / weewxd：https://weewx.com/docs/5.5/utilities/weewxd/
• 官方 Utilities guide / weectl import：https://weewx.com/docs/5.5/utilities/weectl-import/
• 官方 User's guide / Running（systemd 与手工运行）：https://weewx.com/docs/5.5/usersguide/running/
• 站内相关：《WeeWX 介绍与选型指南》 ｜ 《Ubuntu 22.04 安装 WeeWX 5.5.2 指南》 ｜ 《WeeWX 5.5.2 配置参数详解》