Skip to content

feat(platform): add read-only deployment diagnostics page - #1186

Open
linus-liu-web wants to merge 1 commit into
Tencent:mainfrom
linus-liu-web:feat/platform-diagnostics
Open

linus-liu-web wants to merge 1 commit into
Tencent:mainfrom
linus-liu-web:feat/platform-diagnostics

Conversation

@linus-liu-web

Copy link
Copy Markdown

What changed

Operators previously had to run docker exec and query information_schema by hand to notice deployment problems. Three recent cases show the gap:

This adds a read-only 平台管理 → 运维诊断 / Platform administration → Deployment diagnostics page backed by GET /api/platform/diagnostics (platform admins only):

  • Database: connectivity, MySQL version and database name; on non-MySQL storage the object checks are reported as skipped.
  • Observability schema: run_telemetry.adapter / run_logs.level exist and are generated columns, with scripts/install-schema-extensions.sh as the remediation command (installer/./start.sh pull covers Compose).
  • Artifact column capacity: run_artifacts.content type compared with the engine's single-artifact limit (engine.ArtifactSizeLimit(), 1 MiB); TEXT/TINYTEXT warns about the MEDIUMTEXT remedy.
  • Agent browser: sidecar image name and whether it already exists, with the agentflow -browser-image prebuild command; hidden when AGENTFLOW_BROWSER=off.
  • Runtime: Docker availability and whether the configured AGENTFLOW_ISOLATED_IMAGE exists locally.

The page never writes anything and never executes a migration; it only reports state and copyable commands, consistent with the repository policy that operators run migrations/ by hand. The UI follows the existing platform-admin card/tab structure, uses lfT zh/en copy, and has no new dependency.

Related: this implements the proposal in #1185; the artifact-column remedy belongs to the separate widening migration in #1184.

Scope

  • Platform core / API / runner
  • Public adapter / deployment
  • Classic
  • Portable
  • Shared behavior contract
  • Installer / CLI
  • Documentation only

Compatibility

Read-only endpoint, platform-admins only, same auth path as the existing /api/platform/* routes. No schema change and no migration is run. The new page renders inside the existing platform administration view and is only reachable by platform admins. The schema checks require MySQL; other storage drivers report the check as skipped.

Validation

  • go vet ./internal/httpapi ./internal/runtime ./internal/engine ./web passes; gofmt clean.
  • go test ./internal/httpapi -run 'Platform|Diagnostics' -count=1 passes, including the new admin/member access test (member → 403, admin → checks with valid statuses and the expected IDs).
  • go test ./internal/runtime -run 'Browser|DockerImage' -count=1 passes (sidecar image reference reporting, empty-reference guard).
  • go test ./internal/engine -run TestArtifactSizeLimit -count=1 passes.
  • go test ./web -count=1 passes, including the new node test for the panel markup, status classes and counts.
  • python3 scripts/check-public.py passes.
  • Not run: a live deployment check (the page was not exercised against a running platform container), the full go test -p=2 ./..., and scripts/scan-secrets.sh (its scanner download timed out on this network).

Safety

  • I did not include credentials, internal endpoints, production data, or organization-specific infrastructure.
  • I preserved user files and unrelated changes.
  • I updated generated Classic host bundles when applicable. (n/a — no Classic change)
  • I documented third-party content and licensing changes when applicable. (n/a)

Operators had to run docker exec and query information_schema to notice
deployment problems: an artifact over TEXT's 65,535-byte limit fails the run
write with MySQL error 1406 and leaves the node running (Tencent#1092), a missing
generated column surfaces as a raw "Unknown column" error (Tencent#201), and the
Agent browser sidecar image is only discovered on first use (Tencent#1160).

Add 平台管理 → 运维诊断 backed by GET /api/platform/diagnostics (admin only):
- database connectivity and MySQL version;
- run_telemetry.adapter / run_logs.level generated columns, with the command
  that restores them (scripts/install-schema-extensions.sh);
- run_artifacts.content capacity compared with the engine's 1 MiB artifact
  limit (TEXT warns with the MEDIUMTEXT remedy);
- Agent browser sidecar image presence with the prebuild command;
- Docker availability and the configured AGENTFLOW_ISOLATED_IMAGE.

The page only reports and suggests commands; it never runs migrations, keeping
the manual-migration policy. Adds the diagnostics card to the platform admin
tabs with zh/en copy, plus the API, engine/runtime accessors and tests.
@linus-liu-web
linus-liu-web force-pushed the feat/platform-diagnostics branch from 5d1cbd4 to 8f61604 Compare November 21, 2026 18:16
@linus-liu-web

Copy link
Copy Markdown
Author

Rebased onto current main (a458320) after the SOP orchestrator/CodeBuddy merges moved web/index.html, web/app/workbench.js, internal/httpapi/server.go, internal/runtime/sandbox_docker.go, docs/deployment.md and web/platform.css. Only web/index.html needed manual resolution (script insert + workbench.js cache-busting query bumped to 20261122diagnostics); every other hunk applied cleanly.

Re-ran validation on the rebased tree:

  • go vet ./internal/httpapi ./internal/runtime ./internal/engine ./web passes; gofmt clean.
  • go test ./internal/httpapi -run TestPlatformDiagnosticsAPI, ./internal/runtime -run 'TestBrowserSidecarImageReportsReference|TestDockerImageExistsRejectsEmptyReference', ./internal/engine -run TestArtifactSizeLimit, ./web -run TestPlatformDiagnosticsPanel all pass.
  • go test ./web -count=1 (full) passes; python3 scripts/check-public.py passes.

Diff is still 15 files, +676/-1; mergeable: True again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant