pikasTech-HWLAB/docs/dev-edge-health.md

HWLAB DEV Edge Health

This check is DEV-only and targets the frozen endpoint:

node scripts/dev-edge-health-smoke.mjs --live --write-report

The smoke is read-only. It does not touch PROD, restart services, read secrets, or substitute UniDesk backend/provider-gateway/microservice-proxy for HWLAB runtime.

Health Evidence

GET http://74.48.78.17:16667/health must return HWLAB DEV JSON with:

• serviceId for the HWLAB service answering the request;
• environment: "dev";
• commit evidence;
• image evidence;
• service evidence.

hwlab-cloud-api also serves GET /health/live for k3s probes and edge forwarding checks.

db in the cloud-api health payload is a redacted configuration gate. It reports required env names, presence, missing names, and Secret reference names only. Runtime health additionally reports redacted DB readiness layers: configReady, envInjected, connectionAttempted, connectionResult, and liveConnected. It must not expose a connection string, token, password, DB host, username, or claim fixture output as live DB evidence.

Required DEV DB config names:

• HWLAB_CLOUD_DB_URL from Secret reference hwlab-cloud-api-dev-db/database-url.
• HWLAB_CLOUD_DB_SSL_MODE=require.

When the Secret/env is absent, the health JSON should keep db.connected: false, set db.status: "blocked", and list the missing env names so gate reports can identify cloud-api-db-health-gate. When the env is present but no live DB probe is attempted, the gate remains blocked with connectionResult: "not_attempted". When a probe is attempted but liveConnected is false, the gate remains blocked/degraded with the redacted connection classifier. Env presence alone is not live DB evidence.

Route Classification

The smoke classifies failures into these blockers:

• frp_blocker: public :16667 is unavailable and frps control or tunnel health ports also refuse connections.
• edge_proxy_blocker: frps is reachable, but public :16667 refuses.
• k3s_service_blocker: k3s is observable but HWLAB DEV services/endpoints are missing.
• dns_port_firewall_blocker: public endpoint times out or cannot be resolved as a port/network path.
• app_health_blocker: public HTTP reaches an app but health JSON is wrong, missing evidence, returns an HTTP error, or reports DB env injected without a live DB connection.

Machine-Readable Diagnosis

Blocked frp_blocker and edge_proxy_blocker reports now include a diagnosis object in reports/dev-gate/dev-edge-health.json with:

• likelyLayer: the most likely broken layer, such as master-edge/frps;
• confidence: coarse confidence for the diagnosis;
• likelyCause: a single-sentence blocker summary;
• evidence: the TCP probes that support the diagnosis;
• notProven: layers this probe did not rule out;
• nextTask: the smallest read-only follow-up or ops action.

Current Blocker

The committed report at reports/dev-gate/dev-edge-health.json records a read-only live run where public http://74.48.78.17:16667/health/live returned HWLAB DEV health from hwlab-cloud-api, DB config was present, but runtime health still reported no live DB connection attempt/result from the deployed image. Classification: app_health_blocker with likely layer cloud-api-db.

DEV FRP Contract

deploy/frp/frps.dev.toml reserves public 16666 for hwlab-cloud-web and public 16667 as a TCP remotePort for hwlab-dev-edge-proxy. Do not bind vhostHTTPPort = 16667 in the same frps config; that collides with the TCP proxy and can keep the DEV route from registering cleanly.