# 管理面板系统日志 `/admin/system-logs` 为管理员提供 Virt Cloud 运行日志和错误日志的只读查询页面。页面通过 `/api/v1/admin/system-logs` 调用宿主机的 `journalctl`,并支持服务、级别、关键词、时间范围和结果条数筛选。首屏只渲染页面框架,日志由有超时的 API 请求异步读取,避免一次 journal 读取阻塞整个页面;列表请求可手动停止,详情请求也有独立截止时间。 日志读取范围固定为以下服务单元: - `virt-cloud-engine.service` - `virt-cloud-worker.service` - `virt-cloud-lifecycle.service` - `virt-cloud-policy-worker.service` - `virt-cloud-policy-worker@1.service` - `virt-cloud-policy-worker@2.service` - `virt-cloud-update.service` - `libvirtd.service` - `virtqemud.service` - `virtnwfilterd.service` - `virtstoraged.service` - `virtlogd.service` - `virtlockd.service` 接口使用参数数组启动 `/usr/bin/journalctl`(系统没有该路径时使用 `/bin/journalctl`),不会经过 shell,也不接受任意 unit、命令或文件路径。单次最多读取 200 条,使用 `--cursor` 加 `--reverse` 加载更早记录;journalctl 会从游标向更早记录移动,返回结果通常不包含边界,服务端也会防御性移除意外返回的边界记录。这样可以避开部分旧 systemd 版本在 `--after-cursor` 与 unit 筛选组合下漏掉首条记录的问题。带时间下界的游标页会在 PHP 中继续应用下界,因为 systemd 不允许 `--since` 与游标同时出现。消息预览、详情字段、输出、stderr 和子进程运行时间都有上限。每条列表记录保留 journal cursor、服务和 UTC 微秒时间戳,点击后通过 `GET /api/v1/admin/system-logs/detail?cursor=...&unit=...×tamp=...` 在该时间戳窗口内重新读取,再校验返回 cursor,避免不同 systemd 版本的 cursor seek 差异影响详情;日志轮转或游标不存在时返回 404。命令行、可执行文件和 core-dump 字段不会返回,名称明显表示密码、令牌、密钥、凭据或授权信息的结构化字段会隐藏值,消息中的常见凭据形式也会遮罩。日志内容可能包含运行时上下文,因此接口仅对管理员开放,并设置 `private, no-store`。 PHP-FPM 或 Web 服务账号需要具备读取 systemd journal 的权限。部署后如果页面提示无权读取日志,应将该账号加入目标系统的 `systemd-journal` 组并重启 PHP-FPM;不要为了此页面授予 root 权限。 接口读取的是运行 PHP 面板的本机 journal。若引擎部署在独立宿主机,页面不会假装已经读取远程宿主机日志;远程宿主机的 libvirt 错误仍需在该宿主机执行 `journalctl`,或后续增加经过引擎认证的只读日志代理。 列表每一行是可聚焦的详情触发器:鼠标点击行内任意内容、按 Enter 或空格都会打开右侧详情抽屉。详情抽屉使用共享的 `VenixDrawerMotion` 控制器;如果共享脚本未加载,页面会回退到原生 dialog 并显式添加可见状态类。详情请求和抽屉显示相互独立,网络读取失败时仍会显示可定位的错误状态。 页面的时间输入使用面板 PHP 时区,传给 journalctl 时转换为 Unix 时间戳。错误级别对应 journald 的 priority `0..3`,警告为 `4`,其余级别分别对应 `5`、`6`、`7`。