diff --git a/docs/ADMIN_SYSTEM_LOGS.md b/docs/ADMIN_SYSTEM_LOGS.md
new file mode 100644
index 00000000..f8c9e550
--- /dev/null
+++ b/docs/ADMIN_SYSTEM_LOGS.md
@@ -0,0 +1,24 @@
+# 管理面板系统日志
+
+`/admin/system-logs` 为管理员提供 Virt Cloud 运行日志和错误日志的只读查询页面。页面通过 `/api/v1/admin/system-logs` 调用宿主机的 `journalctl`,并支持服务、级别、关键词、时间范围和结果条数筛选。
+
+日志读取范围固定为以下服务单元:
+
+- `virt-cloud-engine.service`
+- `virt-cloud-worker.service`
+- `virt-cloud-lifecycle.service`
+- `virt-cloud-policy-worker@1.service`
+- `virt-cloud-policy-worker@2.service`
+- `virt-cloud-update.service`
+- `libvirtd.service`
+- `virtqemud.service`
+- `virtlogd.service`
+- `virtlockd.service`
+
+接口使用参数数组启动 `/usr/bin/journalctl`(系统没有该路径时使用 `/bin/journalctl`),不会经过 shell,也不接受任意 unit、命令或文件路径。单次最多读取 200 条,使用 journal cursor 加载更早记录;消息长度和游标都有限制。日志内容可能包含运行时上下文,因此接口仅对管理员开放,并设置 `private, no-store`。
+
+PHP-FPM 或 Web 服务账号需要具备读取 systemd journal 的权限。部署后如果页面提示无权读取日志,应将该账号加入目标系统的 `systemd-journal` 组并重启 PHP-FPM;不要为了此页面授予 root 权限。
+
+接口读取的是运行 PHP 面板的本机 journal。若引擎部署在独立宿主机,页面不会假装已经读取远程宿主机日志;远程宿主机的 libvirt 错误仍需在该宿主机执行 `journalctl`,或后续增加经过引擎认证的只读日志代理。
+
+页面的时间输入使用面板 PHP 时区,传给 journalctl 时转换为 Unix 时间戳。错误级别对应 journald 的 priority `0..3`,警告为 `4`,其余级别分别对应 `5`、`6`、`7`。
diff --git a/web/app/Controllers/Admin/CloudPageController.php b/web/app/Controllers/Admin/CloudPageController.php
index 7cfa8f88..672cd375 100644
--- a/web/app/Controllers/Admin/CloudPageController.php
+++ b/web/app/Controllers/Admin/CloudPageController.php
@@ -11,6 +11,7 @@ use App\Services\Cloud\CloudAdminResourceService;
use App\Services\Cloud\CloudCountryCatalog;
use App\Services\Cloud\CloudError;
use App\Services\Cloud\CloudHostInventoryDiagnostics;
+use App\Services\Cloud\CloudSystemJournalService;
use App\Services\Cloud\CloudPlatformDefaultNetworkPolicy;
use App\Services\Cloud\CloudPlatformTestNetworkPolicy;
@@ -268,4 +269,41 @@ final class CloudPageController extends AdminController
$response->getBody()->write($smarty->fetch('admin/cloud/host_inventory.tpl'));
return $response->withStatus($status)->withHeader('Cache-Control', 'private, no-store');
}
+
+ public function systemLogs($request, $response, $args)
+ {
+ try {
+ $actor = CloudAccess::actor(false);
+ } catch (CloudError $exception) {
+ return $response->withStatus($exception->httpStatus)
+ ->withHeader('Cache-Control', 'private, no-store');
+ }
+ if (!($actor['is_admin'] ?? false)) {
+ return $response->withStatus(403)->withHeader('Cache-Control', 'private, no-store');
+ }
+ $payload = null;
+ $error = '';
+ $status = 200;
+ try {
+ $payload = CloudSystemJournalService::page($actor, $request->getQueryParams());
+ } catch (CloudError $exception) {
+ $error = $exception->getMessage();
+ $status = $exception->httpStatus;
+ } catch (\Throwable $exception) {
+ error_log('Admin system journal failed: ' . get_class($exception));
+ $error = '系统日志暂时无法读取,请稍后重试。';
+ $status = 503;
+ }
+ $smarty = $this->view()->assign([
+ 'system_logs_page' => $payload,
+ 'system_logs_error' => $error,
+ 'system_logs_timezone' => date_default_timezone_get(),
+ 'system_logs_bootstrap_json' => json_encode($payload,
+ JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT
+ | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE
+ | JSON_THROW_ON_ERROR),
+ ]);
+ $response->getBody()->write($smarty->fetch('admin/cloud/system_logs.tpl'));
+ return $response->withStatus($status)->withHeader('Cache-Control', 'private, no-store');
+ }
}
diff --git a/web/app/Controllers/CloudAdminSystemLogsController.php b/web/app/Controllers/CloudAdminSystemLogsController.php
new file mode 100644
index 00000000..637b6e88
--- /dev/null
+++ b/web/app/Controllers/CloudAdminSystemLogsController.php
@@ -0,0 +1,19 @@
+getAttribute('cloud_actor') ?? CloudAccess::actor(false),
+ $request->getQueryParams()
+ );
+ return $response->withJson($payload)->withHeader('Cache-Control', 'private, no-store');
+ }
+}
diff --git a/web/app/Middleware/CloudApi.php b/web/app/Middleware/CloudApi.php
index 7ad863b4..a119ccfb 100644
--- a/web/app/Middleware/CloudApi.php
+++ b/web/app/Middleware/CloudApi.php
@@ -19,6 +19,7 @@ final class CloudApi
|| preg_match('#^/api/v1/admin/billing(?:/|$)#D', $path) === 1
|| preg_match('#^/api/v1/admin/instances(?:/|$)#D', $path) === 1
|| preg_match('#^/api/v1/admin/operations(?:/|$)#D', $path) === 1
+ || preg_match('#^/api/v1/admin/system-logs(?:/|$)#D', $path) === 1
|| preg_match('#^/api/v1/admin/host-inventory(?:/|$)#D', $path) === 1
|| preg_match('#^/api/v1/admin/platform-test-policy(?:/|$)#D', $path) === 1
|| preg_match('#^/api/v1/admin/(?:resources|regions|network-lines|resource-pools|resource-reservations)(?:/|$)#D', $path) === 1
diff --git a/web/app/Services/Cloud/CloudSystemJournalService.php b/web/app/Services/Cloud/CloudSystemJournalService.php
new file mode 100644
index 00000000..431d8e42
--- /dev/null
+++ b/web/app/Services/Cloud/CloudSystemJournalService.php
@@ -0,0 +1,353 @@
+ '0..3',
+ 'warning' => '4',
+ 'notice' => '5',
+ 'info' => '6',
+ 'debug' => '7',
+ ];
+
+ private const PRIORITY_LABELS = [
+ 0 => '紧急', 1 => '警报', 2 => '严重', 3 => '错误',
+ 4 => '警告', 5 => '通知', 6 => '信息', 7 => '调试',
+ ];
+
+ public static function page(array $actor, array $input): array
+ {
+ self::authorize($actor);
+ return (new self())->read($input);
+ }
+
+ /**
+ * Parse journalctl's JSON-lines output. Kept public for contract tests and
+ * for deployments that want to validate a captured journal fixture.
+ */
+ public static function parseJournalJson(string $output, ?array $allowedUnits = null): array
+ {
+ $allowed = array_fill_keys($allowedUnits ?? self::UNITS, true);
+ $rows = [];
+ foreach (preg_split('/\r?\n/', $output) ?: [] as $line) {
+ if ($line === '') {
+ continue;
+ }
+ try {
+ $entry = json_decode($line, true, 32,
+ JSON_INVALID_UTF8_SUBSTITUTE | JSON_THROW_ON_ERROR);
+ } catch (\Throwable $ignored) {
+ continue;
+ }
+ if (!is_array($entry)) {
+ continue;
+ }
+ $unit = self::cleanText($entry['_SYSTEMD_UNIT'] ?? '');
+ if ($unit === '' || !isset($allowed[$unit])) {
+ continue;
+ }
+ $priority = filter_var($entry['PRIORITY'] ?? null, FILTER_VALIDATE_INT);
+ if ($priority === false || $priority === null || $priority < 0 || $priority > 7) {
+ $priority = 6;
+ }
+ $micros = filter_var($entry['__REALTIME_TIMESTAMP'] ?? null, FILTER_VALIDATE_INT);
+ $timestamp = $micros !== false && $micros !== null && $micros > 0
+ ? self::timestamp((int) $micros) : null;
+ $message = self::cleanMessage($entry['MESSAGE'] ?? '');
+ $rows[] = [
+ 'timestamp' => $timestamp,
+ 'unit' => $unit,
+ 'priority' => $priority,
+ 'level' => self::PRIORITY_LABELS[$priority],
+ 'message' => $message,
+ 'pid' => self::cleanText($entry['_PID'] ?? ''),
+ 'process' => self::cleanText($entry['_COMM'] ?? ($entry['SYSLOG_IDENTIFIER'] ?? '')),
+ 'hostname' => self::cleanText($entry['_HOSTNAME'] ?? ''),
+ 'cursor' => self::cleanCursor($entry['__CURSOR'] ?? ''),
+ ];
+ }
+ return $rows;
+ }
+
+ private function read(array $input): array
+ {
+ $filters = $this->filters($input);
+ $units = $filters['unit'] === '' ? self::UNITS : [$filters['unit']];
+ $args = [
+ '--no-pager', '--output=json', '--utc', '--all', '--reverse',
+ '--lines=' . min(self::MAX_FETCH_LINES, $filters['limit'] + 1),
+ ];
+ foreach ($units as $unit) {
+ $args[] = '--unit=' . $unit;
+ }
+ if ($filters['priority'] !== '') {
+ $args[] = '--priority=' . self::PRIORITIES[$filters['priority']];
+ }
+ if ($filters['since'] !== '') {
+ $args[] = '--since=@' . $this->epoch($filters['since']);
+ }
+ if ($filters['until'] !== '') {
+ $args[] = '--until=@' . $this->epoch($filters['until']);
+ }
+ if ($filters['cursor'] !== '') {
+ $args[] = '--before-cursor=' . $filters['cursor'];
+ }
+
+ $result = $this->run($args);
+ if ($result['exit_code'] !== 0) {
+ $stderr = strtolower($result['stderr']);
+ if ($result['stdout'] === '' && str_contains($stderr, 'no journal files')) {
+ $result['stdout'] = '';
+ } else {
+ throw new CloudError(
+ '系统日志暂时无法读取,请确认 PHP-FPM 用户有 systemd journal 读取权限。',
+ 503
+ );
+ }
+ }
+
+ $rows = self::parseJournalJson($result['stdout'], $units);
+ if ($filters['query'] !== '') {
+ $needle = function_exists('mb_strtolower')
+ ? mb_strtolower($filters['query'], 'UTF-8') : strtolower($filters['query']);
+ $rows = array_values(array_filter($rows, static function (array $row) use ($needle): bool {
+ $haystack = $row['unit'] . ' ' . $row['process'] . ' ' . $row['message'];
+ $haystack = function_exists('mb_strtolower')
+ ? mb_strtolower($haystack, 'UTF-8') : strtolower($haystack);
+ return str_contains($haystack, $needle);
+ }));
+ }
+
+ $hasMore = count($rows) > $filters['limit'];
+ if ($hasMore) {
+ $rows = array_slice($rows, 0, $filters['limit']);
+ }
+ $nextCursor = $hasMore && $rows !== [] ? ($rows[array_key_last($rows)]['cursor'] ?? null) : null;
+ // A journal without cursors cannot be paged safely; report the
+ // bounded first window instead of presenting a dead “load more” link.
+ $hasMore = $hasMore && $nextCursor !== null && $nextCursor !== '';
+ $errorCount = 0;
+ $warningCount = 0;
+ foreach ($rows as $row) {
+ if ((int) $row['priority'] <= 3) {
+ $errorCount++;
+ } elseif ((int) $row['priority'] === 4) {
+ $warningCount++;
+ }
+ }
+
+ return [
+ 'items' => $rows,
+ 'units' => self::UNITS,
+ 'summary' => [
+ 'total' => count($rows), 'error_count' => $errorCount,
+ 'warning_count' => $warningCount,
+ 'latest_at' => $rows[0]['timestamp'] ?? null,
+ ],
+ 'filters' => [
+ 'unit' => $filters['unit'], 'priority' => $filters['priority'],
+ 'query' => $filters['query'], 'since' => $filters['since'],
+ 'until' => $filters['until'], 'limit' => $filters['limit'],
+ ],
+ 'pagination' => ['next_cursor' => $nextCursor, 'has_more' => $hasMore],
+ 'generated_at' => time(),
+ 'limited' => $hasMore,
+ ];
+ }
+
+ private function filters(array $input): array
+ {
+ $unit = trim((string) ($input['unit'] ?? ''));
+ if ($unit !== '' && !in_array($unit, self::UNITS, true)) {
+ throw new CloudError('日志服务筛选项无效', 400);
+ }
+ $priority = strtolower(trim((string) ($input['priority'] ?? '')));
+ if ($priority !== '' && !isset(self::PRIORITIES[$priority])) {
+ throw new CloudError('日志级别筛选项无效', 400);
+ }
+ $query = trim((string) ($input['query'] ?? ''));
+ if (strlen($query) > self::MAX_QUERY_LENGTH) {
+ throw new CloudError('日志关键词过长', 400);
+ }
+ $limit = (int) ($input['limit'] ?? 100);
+ if (!in_array($limit, [50, 100, 200], true)) {
+ throw new CloudError('日志条数只能为 50、100 或 200', 400);
+ }
+ $since = $this->dateFilter($input['since'] ?? '');
+ $until = $this->dateFilter($input['until'] ?? '');
+ if ($since !== '' && $until !== '' && $this->epoch($since) > $this->epoch($until)) {
+ throw new CloudError('日志开始时间不能晚于结束时间', 400);
+ }
+ $cursor = self::cleanCursor($input['cursor'] ?? '');
+ if ((string) ($input['cursor'] ?? '') !== '' && $cursor === '') {
+ throw new CloudError('日志游标无效', 400);
+ }
+ return compact('unit', 'priority', 'query', 'limit', 'since', 'until', 'cursor');
+ }
+
+ private function dateFilter($value): string
+ {
+ $value = trim((string) $value);
+ if ($value === '') {
+ return '';
+ }
+ if (!preg_match('/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2})?$/D', $value)) {
+ throw new CloudError('日志时间格式无效', 400);
+ }
+ $value = str_replace(' ', 'T', $value);
+ $format = strlen($value) === 16 ? '!Y-m-d\\TH:i' : '!Y-m-d\\TH:i:s';
+ $zone = new DateTimeZone(date_default_timezone_get());
+ $date = DateTimeImmutable::createFromFormat($format, $value, $zone);
+ $errors = DateTimeImmutable::getLastErrors();
+ if (!$date || ($errors !== false && ($errors['warning_count'] || $errors['error_count']))) {
+ throw new CloudError('日志时间无效', 400);
+ }
+ // Keep the canonical value in the panel timezone so datetime-local
+ // controls round-trip correctly. epoch() performs the UTC conversion
+ // only when building journalctl arguments.
+ return $date->format('Y-m-d\\TH:i');
+ }
+
+ private function epoch(string $value): int
+ {
+ $date = new DateTimeImmutable($value, new DateTimeZone(date_default_timezone_get()));
+ return $date->getTimestamp();
+ }
+
+ private function run(array $args): array
+ {
+ $binary = is_executable('/usr/bin/journalctl') ? '/usr/bin/journalctl'
+ : (is_executable('/bin/journalctl') ? '/bin/journalctl' : '');
+ if ($binary === '') {
+ throw new CloudError('系统日志工具 journalctl 不可用', 503);
+ }
+ $stderrPath = tempnam(sys_get_temp_dir(), 'virt-cloud-journal-');
+ if ($stderrPath === false) {
+ throw new CloudError('系统日志读取暂不可用', 503);
+ }
+ $stdin = fopen('/dev/null', 'r');
+ $descriptors = [0 => $stdin, 1 => ['pipe', 'w'], 2 => ['file', $stderrPath, 'a']];
+ $process = proc_open(array_merge([$binary], $args), $descriptors, $pipes, null, null,
+ ['bypass_shell' => true]);
+ if (!is_resource($process)) {
+ @fclose($stdin);
+ @unlink($stderrPath);
+ throw new CloudError('系统日志读取进程无法启动', 503);
+ }
+ stream_set_blocking($pipes[1], false);
+ $stdout = '';
+ $deadline = microtime(true) + self::MAX_PROCESS_SECONDS;
+ $timedOut = false;
+ while (true) {
+ $status = proc_get_status($process);
+ $read = [$pipes[1]];
+ $write = null;
+ $except = null;
+ $remaining = max(0.0, $deadline - microtime(true));
+ $seconds = (int) min(1, floor($remaining));
+ $microseconds = (int) min(999999, max(0, round(($remaining - $seconds) * 1000000)));
+ $ready = $remaining > 0 ? @stream_select($read, $write, $except, $seconds, $microseconds) : 0;
+ if ($ready > 0) {
+ $chunk = fread($pipes[1], 65536);
+ if ($chunk !== false && $chunk !== '') {
+ $stdout .= $chunk;
+ if (strlen($stdout) > self::MAX_OUTPUT_BYTES) {
+ proc_terminate($process, 9);
+ fclose($pipes[1]);
+ proc_close($process);
+ @fclose($stdin);
+ @unlink($stderrPath);
+ throw new CloudError('系统日志输出过大,请缩小时间范围后重试。', 422);
+ }
+ }
+ }
+ if (!$status['running'] && feof($pipes[1])) {
+ break;
+ }
+ if (microtime(true) >= $deadline) {
+ $timedOut = true;
+ proc_terminate($process, 9);
+ break;
+ }
+ }
+ fclose($pipes[1]);
+ $exitCode = proc_close($process);
+ @fclose($stdin);
+ $stderr = (string) @file_get_contents($stderrPath);
+ @unlink($stderrPath);
+ if ($timedOut) {
+ throw new CloudError('读取系统日志超时,请缩小时间范围后重试。', 503);
+ }
+ return ['exit_code' => $exitCode, 'stdout' => (string) $stdout, 'stderr' => $stderr];
+ }
+
+ private static function authorize(array $actor): void
+ {
+ if (!($actor['is_admin'] ?? false)) {
+ throw new CloudError('需要管理员权限', 403);
+ }
+ }
+
+ private static function timestamp(int $micros): string
+ {
+ $seconds = intdiv($micros, 1000000);
+ $fraction = $micros % 1000000;
+ return gmdate('Y-m-d\\TH:i:s', $seconds) . sprintf('.%06dZ', $fraction);
+ }
+
+ private static function cleanMessage($value): string
+ {
+ $value = is_scalar($value) ? (string) $value : json_encode($value, JSON_UNESCAPED_UNICODE);
+ $value = (string) $value;
+ $value = preg_replace('/(?:\\x1B\\[[0-?]*[ -\\/]*[@-~])|[\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]/', '', $value) ?? '';
+ return function_exists('mb_substr') ? mb_substr($value, 0, self::MAX_MESSAGE_LENGTH, 'UTF-8')
+ : substr($value, 0, self::MAX_MESSAGE_LENGTH);
+ }
+
+ private static function cleanText($value): string
+ {
+ return self::cleanMessage($value);
+ }
+
+ private static function cleanCursor($value): string
+ {
+ $value = trim((string) $value);
+ return strlen($value) <= self::MAX_CURSOR_LENGTH
+ && preg_match('/^[A-Za-z0-9_.:;=+@\\/-]+$/D', $value) === 1 ? $value : '';
+ }
+}
diff --git a/web/config/routes.php b/web/config/routes.php
index 5b198798..cd75c641 100644
--- a/web/config/routes.php
+++ b/web/config/routes.php
@@ -174,6 +174,7 @@ $app->group('/admin', function () {
$this->get('/cloud/orders', 'App\Controllers\Admin\CloudPageController:orders');
$this->get('/update', 'App\Controllers\Admin\CloudPageController:update')->add(new SuperAdmin());
$this->get('/operations', 'App\Controllers\Admin\CloudPageController:operations');
+ $this->get('/system-logs', 'App\Controllers\Admin\CloudPageController:systemLogs');
$this->get('/platform-default-policy', 'App\Controllers\Admin\CloudPageController:platformDefaultPolicy');
// Telegram administration is rendered inside the ticket system; these
// action endpoints remain stable for existing sessions and automation.
diff --git a/web/config/routes_cloud.php b/web/config/routes_cloud.php
index 3c301d1c..2f41865a 100644
--- a/web/config/routes_cloud.php
+++ b/web/config/routes_cloud.php
@@ -76,6 +76,7 @@ $app->group('/api/v1', function () {
$this->patch('/admin/instances/{id:[0-9]+}/settings', 'App\Controllers\CloudAdminInstanceController:settings');
$this->get('/admin/operations', 'App\Controllers\CloudAdminOperationsController:index');
$this->get('/admin/operations/health', 'App\Controllers\CloudAdminRuntimeController:index');
+ $this->get('/admin/system-logs', 'App\Controllers\CloudAdminSystemLogsController:index');
$this->get('/admin/operations/jobs/{id:[0-9]+}', 'App\Controllers\CloudAdminOperationsController:detail');
$this->post('/admin/operations/jobs/{id:[0-9]+}/cancel', 'App\Controllers\CloudAdminOperationsController:cancel');
$this->get('/admin/host-inventory', 'App\Controllers\CloudAdminHostInventoryController:index');
diff --git a/web/public/cloud/admin-system-logs.css b/web/public/cloud/admin-system-logs.css
new file mode 100644
index 00000000..24815b06
--- /dev/null
+++ b/web/public/cloud/admin-system-logs.css
@@ -0,0 +1,131 @@
+[data-admin-system-logs] .system-logs-help {
+ display: flex;
+ align-items: flex-end;
+ padding-bottom: 8px;
+}
+
+[data-admin-system-logs] .system-logs-advanced {
+ border-top: 1px solid #e5ebf2;
+ margin-top: 12px;
+ padding-top: 10px;
+}
+
+[data-admin-system-logs] .system-logs-advanced summary {
+ color: #475467;
+ cursor: pointer;
+ font-size: 13px;
+ font-weight: 700;
+}
+
+[data-admin-system-logs] .system-logs-table-wrap {
+ max-height: min(68vh, 760px);
+ overflow: auto;
+}
+
+[data-admin-system-logs] .system-logs-table thead th {
+ background: #f8fafc;
+ color: #667085;
+ font-size: 12px;
+ letter-spacing: .02em;
+ position: sticky;
+ top: 0;
+ white-space: nowrap;
+ z-index: 1;
+}
+
+[data-admin-system-logs] .system-logs-row {
+ cursor: pointer;
+}
+
+[data-admin-system-logs] .system-logs-row:focus-visible {
+ outline: 2px solid #18a87f;
+ outline-offset: -2px;
+}
+
+[data-admin-system-logs] .system-logs-row td:first-child {
+ color: #667085;
+ font-family: var(--bs-font-monospace, monospace);
+ font-size: 12px;
+ white-space: nowrap;
+}
+
+[data-admin-system-logs] .system-logs-message {
+ display: block;
+ max-width: 900px;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+[data-admin-system-logs] .system-logs-level {
+ font-weight: 800;
+ white-space: nowrap;
+}
+
+[data-admin-system-logs] .system-logs-pagination {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+ margin-top: 18px;
+}
+
+[data-admin-system-logs] .system-logs-detail-message {
+ max-height: 420px;
+ margin: 20px 0 0;
+ padding: 16px;
+ border: 1px solid #e5ebf2;
+ border-radius: 8px;
+ background: #f8fafc;
+ color: #1d2939;
+ font: 13px/1.65 var(--bs-font-monospace, monospace);
+ overflow: auto;
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+}
+
+@media (max-width: 767.98px) {
+ [data-admin-system-logs] .system-logs-help {
+ padding-bottom: 0;
+ }
+
+ [data-admin-system-logs] .system-logs-table thead {
+ display: none;
+ }
+
+ [data-admin-system-logs] .system-logs-table,
+ [data-admin-system-logs] .system-logs-table tbody,
+ [data-admin-system-logs] .system-logs-table tr,
+ [data-admin-system-logs] .system-logs-table td {
+ display: block;
+ width: 100%;
+ }
+
+ [data-admin-system-logs] .system-logs-table tr {
+ border-bottom: 1px solid #e5ebf2;
+ padding: 10px 0;
+ }
+
+ [data-admin-system-logs] .system-logs-table td {
+ border: 0;
+ padding: 5px 0 5px 42%;
+ position: relative;
+ text-align: right;
+ }
+
+ [data-admin-system-logs] .system-logs-table td::before {
+ color: #667085;
+ content: attr(data-label);
+ font-size: 12px;
+ font-weight: 700;
+ left: 0;
+ position: absolute;
+ text-align: left;
+ top: 5px;
+ }
+
+ [data-admin-system-logs] .system-logs-message {
+ max-width: none;
+ white-space: normal;
+ }
+}
diff --git a/web/public/cloud/admin-system-logs.js b/web/public/cloud/admin-system-logs.js
new file mode 100644
index 00000000..4bc5be17
--- /dev/null
+++ b/web/public/cloud/admin-system-logs.js
@@ -0,0 +1,223 @@
+const root = document.querySelector('[data-admin-system-logs]');
+const config = window.__VENIX_SYSTEM_LOGS__ || {apiUrl: '/api/v1/admin/system-logs', timezone: 'UTC'};
+const byId = id => document.getElementById(id);
+const state = {page: null, request: null, cursor: null, loading: false};
+const priorityLabels = {0: '紧急', 1: '警报', 2: '严重', 3: '错误', 4: '警告', 5: '通知', 6: '信息', 7: '调试'};
+
+function text(value, fallback = '未记录') {
+ return value === null || value === undefined || String(value).trim() === '' ? fallback : String(value);
+}
+
+function timestamp(value) {
+ if (value === null || value === undefined || value === '') return null;
+ const numeric = Number(value);
+ const date = Number.isFinite(numeric)
+ ? new Date(numeric < 100000000000 ? numeric * 1000 : numeric)
+ : new Date(String(value));
+ return Number.isFinite(date.getTime()) ? date : null;
+}
+
+function date(value) {
+ const parsed = timestamp(value);
+ if (!parsed) return '时间未记录';
+ return parsed.toLocaleString('zh-CN', {hour12: false, timeZone: root?.dataset.timezone || config.timezone || 'UTC'});
+}
+
+function level(item) {
+ const raw = item.level ?? item.priority_label ?? item.priority ?? item.PRIORITY;
+ if (typeof raw === 'number' || /^\d+$/.test(String(raw))) return priorityLabels[Number(raw)] || `级别 ${raw}`;
+ const value = text(raw, 'info').toLowerCase();
+ return ({emerg: '紧急', alert: '警报', crit: '严重', critical: '严重', err: '错误', error: '错误', warning: '警告', warn: '警告', notice: '通知', info: '信息', debug: '调试'})[value] || text(raw, '信息');
+}
+
+function levelClass(item) {
+ const raw = String(item.priority ?? item.PRIORITY ?? item.level ?? item.priority_label ?? '').toLowerCase();
+ if (['0', '1', '2', '3', 'emerg', 'alert', 'crit', 'critical', 'err', 'error'].includes(raw)) return 'text-danger';
+ if (['4', 'warning', 'warn'].includes(raw)) return 'text-warning';
+ return 'text-muted';
+}
+
+function normalizeItem(item) {
+ const source = item && typeof item === 'object' ? item : {};
+ return {
+ timestamp: source.timestamp ?? source.time ?? source.at ?? source.__REALTIME_TIMESTAMP ?? source._SOURCE_REALTIME_TIMESTAMP ?? source.realtime_timestamp,
+ unit: source.unit ?? source.service ?? source.source ?? source._SYSTEMD_UNIT ?? source.syslog_identifier ?? '系统',
+ priority: source.priority ?? source.PRIORITY ?? source.level,
+ level: source.level ?? source.priority_label ?? source.priority ?? source.PRIORITY,
+ message: source.message ?? source.MESSAGE ?? source.msg ?? source.text ?? '',
+ pid: source.pid ?? source._PID ?? '',
+ process: source.process ?? source._COMM ?? source.syslog_identifier ?? '',
+ hostname: source.hostname ?? source._HOSTNAME ?? '',
+ cursor: source.cursor ?? source.__CURSOR ?? null,
+ };
+}
+
+function normalizePayload(payload) {
+ const candidate = payload && payload.data && typeof payload.data === 'object' ? payload.data : payload;
+ if (!candidate || typeof candidate !== 'object') throw new Error('日志响应格式无效,请稍后重试。');
+ const rawItems = Array.isArray(candidate.items) ? candidate.items : (Array.isArray(candidate.rows) ? candidate.rows : []);
+ const items = rawItems.map(normalizeItem);
+ const summary = candidate.summary && typeof candidate.summary === 'object' ? candidate.summary : {};
+ return {
+ items,
+ units: Array.isArray(candidate.units) ? candidate.units.map(String) : [],
+ summary: {
+ total: Number(summary.total ?? candidate.total ?? items.length) || 0,
+ error_count: Number(summary.error_count ?? summary.errors ?? candidate.error_count ?? 0) || 0,
+ warning_count: Number(summary.warning_count ?? summary.warnings ?? candidate.warning_count ?? 0) || 0,
+ latest_at: summary.latest_at ?? (items[0]?.timestamp ?? null),
+ },
+ filters: candidate.filters || {},
+ pagination: {
+ ...(candidate.pagination || {}),
+ next_cursor: candidate.pagination?.next_cursor ?? candidate.pagination?.nextCursor ?? candidate.next_cursor ?? null,
+ has_more: Boolean(candidate.pagination?.has_more ?? candidate.pagination?.hasMore ?? candidate.has_more ?? false),
+ },
+ };
+}
+
+function notice(message, error = false) {
+ const node = byId('system-logs-notice');
+ if (!node) return;
+ node.textContent = message;
+ node.className = `admin-config-status ${error ? 'is-error' : 'is-success'}`;
+ node.setAttribute('role', error ? 'alert' : 'status');
+}
+
+function filterForm() { return byId('system-logs-filter'); }
+
+function queryUrl(cursor = null) {
+ const url = new URL(config.apiUrl, window.location.origin);
+ const form = filterForm();
+ ['unit', 'priority', 'query', 'since', 'until', 'limit'].forEach(name => {
+ const value = form?.elements.namedItem(name)?.value?.trim();
+ if (value) url.searchParams.set(name, value);
+ });
+ if (cursor) url.searchParams.set('cursor', cursor);
+ return url;
+}
+
+function setBusy(value) {
+ state.loading = value;
+ byId('system-logs-refresh').disabled = value;
+ byId('system-logs-older').disabled = value || !state.page?.pagination?.has_more;
+ byId('system-logs-newer').disabled = value;
+ byId('system-logs-body').setAttribute('aria-busy', String(value));
+}
+
+function renderSummary(page) {
+ byId('system-logs-total').textContent = page.summary.total.toLocaleString('zh-CN');
+ byId('system-logs-errors').textContent = page.summary.error_count.toLocaleString('zh-CN');
+ byId('system-logs-warnings').textContent = page.summary.warning_count.toLocaleString('zh-CN');
+ byId('system-logs-latest').textContent = page.summary.latest_at ? date(page.summary.latest_at) : '尚无记录';
+ byId('system-logs-count').textContent = `共 ${page.summary.total.toLocaleString('zh-CN')} 条`;
+ byId('system-logs-page-label').textContent = page.pagination.has_more ? '当前窗口 · 可继续加载' : '当前窗口 · 已到末尾';
+}
+
+function renderUnits(page) {
+ const select = byId('system-logs-unit');
+ if (!select || !Array.isArray(page.units) || !page.units.length) return;
+ const selected = select.value;
+ const values = [...new Set(page.units.map(String).filter(Boolean))].sort();
+ select.replaceChildren(new Option('全部服务', ''));
+ values.forEach(unit => select.add(new Option(unit, unit)));
+ if (values.includes(selected)) select.value = selected;
+}
+
+function renderRows(page) {
+ const body = byId('system-logs-body');
+ body.replaceChildren();
+ if (!page.items.length) {
+ const row = document.createElement('tr');
+ const cell = document.createElement('td'); cell.colSpan = 4; cell.className = 'text-center text-muted py-4'; cell.textContent = '没有符合条件的日志';
+ row.append(cell); body.append(row); return;
+ }
+ page.items.forEach(item => {
+ const row = document.createElement('tr'); row.tabIndex = 0; row.className = 'system-logs-row';
+ const values = [date(item.timestamp), text(item.unit, '系统'), level(item), text(item.message, '消息未记录')];
+ values.forEach((value, index) => {
+ const cell = document.createElement('td'); cell.dataset.label = ['时间', '服务', '级别', '消息'][index];
+ if (index === 2) { const badge = document.createElement('span'); badge.className = `system-logs-level ${levelClass(item)}`; badge.textContent = value; cell.append(badge); }
+ else if (index === 3) { const message = document.createElement('span'); message.className = 'system-logs-message'; message.textContent = value; cell.append(message); }
+ else cell.textContent = value;
+ row.append(cell);
+ });
+ const open = () => openDetail(item);
+ row.addEventListener('click', open);
+ row.addEventListener('keydown', event => { if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); open(); } });
+ body.append(row);
+ });
+}
+
+function render(page) {
+ renderUnits(page); renderSummary(page); renderRows(page);
+ byId('system-logs-older').disabled = state.loading || !page.pagination.has_more;
+}
+
+async function load(cursor = null, replace = true) {
+ state.request?.abort();
+ const controller = new AbortController(); state.request = controller; setBusy(true);
+ notice('正在读取 journal 日志…');
+ try {
+ const response = await fetch(queryUrl(cursor), {headers: {Accept: 'application/json'}, credentials: 'same-origin', cache: 'no-store', signal: controller.signal});
+ let payload; try { payload = await response.json(); } catch { throw new Error('服务器响应格式无效,请稍后重试。'); }
+ if (response.status === 401) throw new Error('登录已过期,请重新登录。');
+ if (response.status === 403) throw new Error('当前账号没有读取系统日志的权限。');
+ if (!response.ok) throw new Error(typeof payload?.detail === 'string' ? payload.detail : '系统日志暂不可读取,请稍后重试。');
+ const page = normalizePayload(payload);
+ if (replace || !state.page) state.page = page;
+ else {
+ const items = [...state.page.items, ...page.items];
+ const errorCount = items.filter(item => Number(item.priority) <= 3).length;
+ const warningCount = items.filter(item => Number(item.priority) === 4).length;
+ state.page = {...page, items, summary: {...page.summary, total: items.length, error_count: errorCount, warning_count: warningCount, latest_at: state.page.summary.latest_at || page.summary.latest_at}};
+ }
+ state.cursor = page.pagination.next_cursor || null;
+ render(state.page);
+ notice(`已读取 ${state.page.items.length} 条日志;仅读取 journal,不会执行宿主机操作。`);
+ } catch (error) {
+ if (controller.signal.aborted) return;
+ notice(error.message || '系统日志暂不可读取,请稍后重试。', true);
+ if (!state.page) { state.page = normalizePayload({items: [], summary: {}}); render(state.page); }
+ } finally {
+ if (state.request === controller) { state.request = null; setBusy(false); }
+ }
+}
+
+function openDetail(item) {
+ const dialog = byId('system-logs-detail');
+ byId('system-logs-detail-title').textContent = `${text(item.unit, '系统')} · ${level(item)}`;
+ const meta = byId('system-logs-detail-meta'); meta.replaceChildren();
+ [['时间', date(item.timestamp)], ['服务', text(item.unit)], ['级别', level(item)], ['进程', text(item.process, '未记录')], ['PID', text(item.pid, '未记录')], ['宿主机', text(item.hostname, '未记录')], ['游标', text(item.cursor, '未记录')]].forEach(([label, value]) => {
+ const dt = document.createElement('dt'); dt.textContent = label; const dd = document.createElement('dd'); dd.className = 'text-break'; dd.textContent = value; meta.append(dt, dd);
+ });
+ byId('system-logs-detail-message').textContent = text(item.message, '消息未记录');
+ if (!dialog.open) dialog.showModal();
+}
+
+function applyUrlToForm() {
+ const url = new URL(window.location.href); const form = filterForm();
+ ['unit', 'priority', 'query', 'since', 'until', 'limit'].forEach(name => {
+ const control = form?.elements.namedItem(name); if (control && url.searchParams.has(name)) control.value = url.searchParams.get(name);
+ });
+}
+
+filterForm()?.addEventListener('submit', event => {
+ event.preventDefault(); const url = new URL(window.location.href);
+ ['unit', 'priority', 'query', 'since', 'until', 'limit'].forEach(name => { const value = filterForm().elements.namedItem(name)?.value?.trim(); if (value) url.searchParams.set(name, value); else url.searchParams.delete(name); });
+ history.pushState(history.state, '', url); state.page = null; state.cursor = null; load();
+});
+byId('system-logs-refresh')?.addEventListener('click', () => load());
+byId('system-logs-newer')?.addEventListener('click', () => load());
+byId('system-logs-older')?.addEventListener('click', () => { if (state.cursor) load(state.cursor, false); });
+byId('system-logs-detail-close')?.addEventListener('click', () => byId('system-logs-detail').close());
+byId('system-logs-detail')?.addEventListener('click', event => { if (event.target === byId('system-logs-detail')) byId('system-logs-detail').close(); });
+window.addEventListener('popstate', () => { applyUrlToForm(); state.page = null; state.cursor = null; load(); });
+
+applyUrlToForm();
+let hasBootstrap = false;
+try {
+ const bootstrap = JSON.parse(document.getElementById('admin-system-logs-bootstrap')?.textContent || 'null');
+ if (bootstrap) { state.page = normalizePayload(bootstrap); state.cursor = state.page.pagination.next_cursor || null; render(state.page); hasBootstrap = true; }
+} catch (error) { /* Fetch below will report the usable error. */ }
+if (!hasBootstrap) load();
diff --git a/web/resources/views/venix/admin/cloud/system_logs.tpl b/web/resources/views/venix/admin/cloud/system_logs.tpl
new file mode 100644
index 00000000..67b8e668
--- /dev/null
+++ b/web/resources/views/venix/admin/cloud/system_logs.tpl
@@ -0,0 +1,54 @@
+{assign var=admin_title value='系统日志'}
+{assign var=admin_active value='system-logs'}
+{include file='admin/static_header.tpl'}
+
+{if !$system_logs_page}
+ {assign var=system_logs_page value=['items'=>[],'units'=>[],'summary'=>['total'=>0,'error_count'=>0,'warning_count'=>0,'latest_at'=>''],'filters'=>['unit'=>'','priority'=>'','query'=>'','since'=>'','until'=>'','limit'=>100],'pagination'=>['next_cursor'=>'','has_more'=>false]]}
+{/if}
+{assign var=system_logs_filters value=$system_logs_page.filters|default:[]}
+{assign var=system_logs_limit value=$system_logs_filters.limit|default:100}
+
+
+
+
Runtime observability
+
系统日志
+
读取面板和宿主机服务保留的 journal 日志,支持按服务、级别、时间和关键词定位错误。查看日志不会执行宿主机操作。
+
+
+ {if $system_logs_error|default:''}{$system_logs_error|escape}{else}已读取 {$system_logs_page.summary.total|default:0|escape} 条日志{/if}
+
+
+
+
+
+ 当前日志
{$system_logs_page.summary.total|default:0|escape}
+ 错误
{$system_logs_page.summary.error_count|default:0|escape}
+ 警告
{$system_logs_page.summary.warning_count|default:0|escape}
+ 最新时间
{if $system_logs_page.summary.latest_at}{$system_logs_page.summary.latest_at|escape}{else}尚无记录{/if}
+
+
+
+
+
+
+ 系统 journal 运行日志| 时间 | 服务 | 级别 | 消息 |
{if !$system_logs_page.items}| 没有符合条件的日志 |
{else}{foreach $system_logs_page.items as $item}| {$item.timestamp|default:'时间未记录'|escape} | {$item.unit|default:'系统'|escape} | {$item.level|default:'信息'|escape} | {$item.message|default:'消息未记录'|escape} |
{/foreach}{/if}
+
+
+
+
+
+
+
+{include file='admin/static_footer.tpl'}
diff --git a/web/resources/views/venix/admin/static_header.tpl b/web/resources/views/venix/admin/static_header.tpl
index 40aaf0df..b5c45545 100644
--- a/web/resources/views/venix/admin/static_header.tpl
+++ b/web/resources/views/venix/admin/static_header.tpl
@@ -190,6 +190,7 @@
平台默认策略
+ 系统日志
diff --git a/web/tests/AdminSystemLogsContractTest.php b/web/tests/AdminSystemLogsContractTest.php
new file mode 100644
index 00000000..569cd844
--- /dev/null
+++ b/web/tests/AdminSystemLogsContractTest.php
@@ -0,0 +1,106 @@
+ 'virt-cloud-engine.service',
+ 'PRIORITY' => '3',
+ '__REALTIME_TIMESTAMP' => '1791273697115460',
+ 'MESSAGE' => "engine failed\x1b[31m\nwith control",
+ '_PID' => '12', '_COMM' => 'python', '_HOSTNAME' => 'host-a',
+ '__CURSOR' => 's=abc;i=1',
+ ], JSON_UNESCAPED_UNICODE),
+ // Entries from other units must not cross the service allowlist.
+ json_encode([
+ '_SYSTEMD_UNIT' => 'ssh.service', 'PRIORITY' => 3,
+ 'MESSAGE' => 'private host log',
+ ], JSON_UNESCAPED_UNICODE),
+ '{invalid json',
+ json_encode([
+ '_SYSTEMD_UNIT' => 'virt-cloud-worker.service',
+ 'PRIORITY' => 99, 'MESSAGE' => 'invalid priority is normalized',
+ ], JSON_UNESCAPED_UNICODE),
+]);
+$rows = \App\Services\Cloud\CloudSystemJournalService::parseJournalJson($fixture);
+$assert(count($rows) === 2, 'Journal parser must ignore malformed and disallowed units.');
+$assert($rows[0]['unit'] === 'virt-cloud-engine.service'
+ && $rows[0]['priority'] === 3
+ && $rows[0]['timestamp'] === '2026-10-06T08:01:37.115460Z',
+ 'Journal timestamp, unit and priority normalization changed.');
+$assert(!str_contains($rows[0]['message'], "\x1b")
+ && !str_contains($rows[0]['message'], "\x0a"),
+ 'Journal message control characters must be removed before rendering.');
+$assert($rows[1]['priority'] === 6 && $rows[1]['level'] === '信息',
+ 'Out-of-range journal priorities must normalize to informational logs.');
+
+$routes = file_get_contents($root . '/config/routes.php');
+$apiRoutes = file_get_contents($root . '/config/routes_cloud.php');
+$middleware = file_get_contents($root . '/app/Middleware/CloudApi.php');
+$pageController = file_get_contents($root . '/app/Controllers/Admin/CloudPageController.php');
+$apiController = file_get_contents($root . '/app/Controllers/CloudAdminSystemLogsController.php');
+$service = file_get_contents($root . '/app/Services/Cloud/CloudSystemJournalService.php');
+$template = file_get_contents($root . '/resources/views/venix/admin/cloud/system_logs.tpl');
+$header = file_get_contents($root . '/resources/views/venix/admin/static_header.tpl');
+$browser = file_get_contents($root . '/public/cloud/admin-system-logs.js');
+
+$assert(substr_count($routes,
+ "get('/system-logs', 'App\\Controllers\\Admin\\CloudPageController:systemLogs')") === 1,
+ 'Administrator system log page route is missing or duplicated.');
+$assert(substr_count($apiRoutes,
+ "get('/admin/system-logs', 'App\\Controllers\\CloudAdminSystemLogsController:index')") === 1
+ && str_contains($middleware, '/api/v1/admin/system-logs'),
+ 'System journal API route or its API middleware boundary is missing.');
+$assert(str_contains($pageController, 'public function systemLogs(')
+ && str_contains($pageController, "CloudAccess::actor(false)")
+ && str_contains($pageController, "system_logs_bootstrap_json")
+ && str_contains($pageController, "admin/cloud/system_logs.tpl"),
+ 'The page controller must authorize a local administrator and bootstrap safe data.');
+$assert(str_contains($apiController, 'CloudSystemJournalService::page(')
+ && str_contains($apiController, "getAttribute('cloud_actor')"),
+ 'The API controller must use the journal service and authenticated cloud actor.');
+
+$assert(str_contains($service, "'/usr/bin/journalctl'")
+ && str_contains($service, "'--output=json'")
+ && str_contains($service, "'bypass_shell' => true")
+ && str_contains($service, 'private static function authorize('),
+ 'Journal reads must use fixed journalctl JSON arguments without a shell.');
+$assert(str_contains($service, 'private const UNITS = [')
+ && str_contains($service, 'virt-cloud-engine.service')
+ && str_contains($service, 'MAX_FETCH_LINES')
+ && str_contains($service, 'MAX_MESSAGE_LENGTH')
+ && str_contains($service, 'MAX_CURSOR_LENGTH'),
+ 'Journal service must keep a fixed unit allowlist and bounded output.');
+$assert(!str_contains($service, 'shell_exec(')
+ && !str_contains($service, 'exec(')
+ && !str_contains($service, 'system(')
+ && !str_contains($service, 'popen('),
+ 'Journal service must not execute user-controlled shell commands.');
+
+$assert(str_contains($template, 'system_logs_bootstrap_json|default:\'null\' nofilter')
+ && str_contains($pageController, 'JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT'),
+ 'The template must only render the controller-produced, JSON-hex-escaped bootstrap.');
+$assert(str_contains($header, 'href="/admin/system-logs"')
+ && str_contains($header, "admin_active|default:'' == 'system-logs'"),
+ 'Administrator navigation must expose the system log page with active state.');
+$assert(!str_contains($browser, 'innerHTML')
+ && str_contains($browser, "credentials: 'same-origin'")
+ && str_contains($browser, 'AbortController')
+ && str_contains($browser, '/api/v1/admin/system-logs'),
+ 'Browser log rendering must remain text-only, same-origin and cancellable.');
+
+echo "Administrator system journal route, parser, authorization and safety contracts passed.\n";