feat: add tunnel diagnostics and protocol templates

Author: gitlayzer

README.md

@@ -12,8 +12,9 @@ Sealtun 是一款功能强大、设计优雅的 CLI 工具，旨在为 **Sealos
 - 🌍 **区域切换**：支持查看已内置的 Sealos Cloud region，并通过 `sealtun region use` 重新登录切换区域。
 - 👤 **Profile 多账号管理**：可把不同 Sealos 账号、region、workspace 和 kubeconfig 保存为命名 profile，按需切换。
 - 🚀 **一键暴露服务**：执行 `sealtun expose 8080`，即可获得一个受信任的 HTTPS URL，将流量安全地路由到本地。
-- 🌐 **自定义域名**：新建隧道时可用 `--domain` 生成 CNAME 指引，并通过 `domain status/doctor` 检查 DNS、Ingress 与证书状态。
-- 📊 **本地控制台与观测**：`dashboard` 提供本地 Web 控制台，`logs`、`events` 和 `metrics` 可查看远端 Pod 日志、Kubernetes 事件、请求计数与运行状态。
+- 🌐 **自定义域名自动化**：可用 `domain plan/add/verify/status/doctor` 生成 CNAME 指引、等待 DNS、绑定域名并检查证书状态。
+- 📊 **状态与诊断**：`doctor <tunnel-id>`、`inspect --remote`、`logs`、`events` 和 `metrics` 可定位本地端口、daemon、远端 Pod、Service、Ingress 与证书问题。
+- 🧩 **协议模板**：`template https|ssh|tcp|mysql|postgres|redis|mqtt` 可生成直接命令和 `sealtun.yaml` 示例。
 - 🧾 **声明式配置**：`apply -f sealtun.yaml` 可用 YAML 声明隧道，并以稳定名称幂等创建或更新。
 - 🌐 **深度适配 Sealos**：原生使用 Sealos Cloud 的 Kubernetes、Service 与 Ingress 能力，当前稳定支持 HTTPS 入口和 WebSocket 隧道。
 - 🐳 **全能二进制文件**：客户端和服务器代理共用同一个精简的二进制文件和 Docker 镜像。
@@ -247,7 +248,14 @@ sealtun expose 3000 --domain app.example.com --wait-domain
 
 或者在 DNS 生效后对已有隧道绑定：
 ```bash
+# 先查看需要配置的 DNS
+sealtun domain plan <tunnel-id> app.example.com
+
+# DNS 已经生效后绑定
 sealtun domain set <tunnel-id> app.example.com
+
+# 或者等待 DNS 生效后自动绑定，并继续等待证书就绪
+sealtun domain add <tunnel-id> app.example.com --wait --timeout 5m
 ```
 
 Sealtun 会保留一个 Sealos 官方子域名作为隧道控制面和 CNAME 目标。只有 CNAME 已经指向该 Sealos host 后，Sealtun 才会把自定义域名写入 Ingress，并创建 cert-manager `Issuer` 与 `Certificate`。你需要在自己的 DNS 服务商处配置：
@@ -294,6 +302,16 @@ sealtun events <tunnel-id>
 sealtun events <tunnel-id> --json
 ```
 
+一键诊断本地与远端状态：
+```bash
+# 全局健康检查
+sealtun doctor
+
+# 单条隧道诊断，会给出本地端口、daemon、远端资源和下一步建议
+sealtun doctor <tunnel-id>
+sealtun doctor <tunnel-id> --json
+```
+
 `metrics` 会聚合本地 session 状态、远端 Deployment/Pod/Ingress 状态，并在远端 Pod 支持时读取受 Bearer secret 保护的 `/_sealtun/metrics` 请求计数。TCP/SSH 四层隧道还会暴露 TCP 连接数、活跃连接数、字节数和错误数。
 
 启动本地只读控制台：
@@ -306,7 +324,19 @@ sealtun dashboard --addr 127.0.0.1 --port 19777
 
 Dashboard 仅监听本地地址，数据来自当前 CLI 进程读取到的本地 session、登录状态、远端诊断和自定义域名状态。
 
-### 7. 声明式配置
+### 7. 协议模板
+不确定该怎么写命令或声明式配置时，可以先生成模板：
+
+```bash
+sealtun template https --name web --port 3000 --domain app.example.com
+sealtun template ssh
+sealtun template postgres
+sealtun template redis --name cache
+```
+
+模板会同时输出一次性 `sealtun expose` 命令和可提交到项目内的 `sealtun.yaml` 片段。`mysql`、`postgres`、`redis`、`mqtt` 模板默认走通用 TCP 四层入口；HTTPS 模板才支持自定义域名和访问控制。
+
+### 8. 声明式配置
 创建 `sealtun.yaml`：
 ```yaml
 version: v1

README_EN.md

@@ -12,8 +12,9 @@ It connects your local development machine straight to the internet by dynamical
 - 🌍 **Region Switching**: List built-in Sealos Cloud regions and switch regions by re-running login with `sealtun region use`.
 - 👤 **Named Profiles**: Save different Sealos accounts, regions, workspaces, and kubeconfigs as named profiles and switch between them.
 - 🚀 **One-Command Expose**: Execute `sealtun expose 8080`, and get a fully trusted HTTPS URL for your localhost securely routed.
-- 🌐 **Custom Domains**: Use `--domain` to print the required CNAME target and `domain status/doctor` to diagnose DNS, Ingress, and certificate readiness.
-- 📊 **Local Console and Observability**: Use `dashboard` for a local web console, and `logs` / `events` / `metrics` for remote pod logs, Kubernetes events, request counters, and runtime state.
+- 🌐 **Custom Domain Automation**: Use `domain plan/add/verify/status/doctor` to generate CNAME guidance, wait for DNS, attach domains, and inspect certificate readiness.
+- 📊 **Status and Diagnostics**: Use `doctor <tunnel-id>`, `inspect --remote`, `logs`, `events`, and `metrics` to diagnose local ports, daemon state, remote Pods, Services, Ingresses, and certificates.
+- 🧩 **Protocol Templates**: Use `template https|ssh|tcp|mysql|postgres|redis|mqtt` to generate commands and `sealtun.yaml` examples.
 - 🧾 **Declarative Config**: Use `apply -f sealtun.yaml` to declare tunnels in YAML and create or update them with stable names.
 - 🌐 **Optimized for Sealos**: Native support for Sealos Cloud domains, HTTPS traffic, and WebSocket tunnels.
 - 🐳 **All-in-One Binary**: The client and the server agent live comfortably in the exact same compact binary and Docker image.
@@ -247,7 +248,14 @@ sealtun expose 3000 --domain app.example.com --wait-domain
 
 Or attach one to an existing tunnel after DNS is ready:
 ```bash
+# Show the DNS record you need first
+sealtun domain plan <tunnel-id> app.example.com
+
+# Attach after DNS is ready
 sealtun domain set <tunnel-id> app.example.com
+
+# Or wait for DNS, attach automatically, and keep waiting for certificate readiness
+sealtun domain add <tunnel-id> app.example.com --wait --timeout 5m
 ```
 
 Sealtun keeps a Sealos-managed host as the tunnel control endpoint and CNAME target. It writes the custom host to Ingress and creates cert-manager `Issuer` and `Certificate` resources only after the CNAME points to that Sealos host. Configure DNS at your provider:
@@ -294,6 +302,16 @@ sealtun events <tunnel-id>
 sealtun events <tunnel-id> --json
 ```
 
+Run local and remote diagnostics:
+```bash
+# Global health check
+sealtun doctor
+
+# Single-tunnel diagnosis with local port, daemon, remote resource, and next-step suggestions
+sealtun doctor <tunnel-id>
+sealtun doctor <tunnel-id> --json
+```
+
 `metrics` combines local session state, remote Deployment/Pod/Ingress readiness, and server-side request counters when the remote pod supports the Bearer-secret-protected `/_sealtun/metrics` endpoint. TCP/SSH tunnels also expose TCP connection, active connection, byte, and error counters.
 
 Run the local read-only dashboard:
@@ -306,7 +324,19 @@ sealtun dashboard --addr 127.0.0.1 --port 19777
 
 The dashboard listens locally and reads the same data as the CLI: local sessions, login state, remote diagnostics, and custom domain readiness.
 
-### 7. Declarative config
+### 7. Protocol templates
+When you are unsure which command or declarative config to use, generate a template first:
+
+```bash
+sealtun template https --name web --port 3000 --domain app.example.com
+sealtun template ssh
+sealtun template postgres
+sealtun template redis --name cache
+```
+
+Templates print both a one-shot `sealtun expose` command and a `sealtun.yaml` snippet. `mysql`, `postgres`, `redis`, and `mqtt` templates default to generic TCP L4 entries; only HTTPS templates support custom domains and access controls.
+
+### 8. Declarative config
 Create `sealtun.yaml`:
 ```yaml
 version: v1

cmd/doctor.go

@@ -5,9 +5,12 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"strings"
 	"sync"
 	"time"
 
+	"github.com/labring/sealtun/pkg/k8s"
+	"github.com/labring/sealtun/pkg/session"
 	"github.com/spf13/cobra"
 )
 
@@ -31,12 +34,50 @@ type doctorPayload struct {
 	Warnings             []string `json:"warnings,omitempty"`
 }
 
+type tunnelDoctorPayload struct {
+	TunnelID           string                 `json:"tunnelId"`
+	Status             string                 `json:"status"`
+	Protocol           string                 `json:"protocol,omitempty"`
+	Endpoint           string                 `json:"endpoint,omitempty"`
+	LocalTarget        string                 `json:"localTarget,omitempty"`
+	Mode               string                 `json:"mode,omitempty"`
+	Namespace          string                 `json:"namespace,omitempty"`
+	ProcessAlive       bool                   `json:"processAlive"`
+	LocalPortReachable bool                   `json:"localPortReachable"`
+	Remote             *k8s.TunnelDiagnostics `json:"remote,omitempty"`
+	Checks             []doctorCheck          `json:"checks"`
+	Suggestions        []string               `json:"suggestions,omitempty"`
+	Warnings           []string               `json:"warnings,omitempty"`
+}
+
+type doctorCheck struct {
+	Name   string `json:"name"`
+	Status string `json:"status"`
+	Detail string `json:"detail,omitempty"`
+}
+
 var doctorJSON bool
 
 var doctorCmd = &cobra.Command{
-	Use:   "doctor",
-	Short: "Run local Sealtun diagnostics",
+	Use:          "doctor [tunnel-id]",
+	Short:        "Run Sealtun diagnostics",
+	Args:         cobra.MaximumNArgs(1),
+	SilenceUsage: true,
 	RunE: func(cmd *cobra.Command, args []string) error {
+		if len(args) > 0 {
+			payload, err := collectTunnelDoctorPayload(cmd.Context(), args[0])
+			if err != nil {
+				return err
+			}
+			if doctorJSON {
+				enc := json.NewEncoder(cmd.OutOrStdout())
+				enc.SetIndent("", "  ")
+				return enc.Encode(payload)
+			}
+			printTunnelDoctor(cmd, payload)
+			return nil
+		}
+
 		payload, err := collectDoctorPayloadWithContext(cmd.Context())
 		if err != nil {
 			return err
@@ -62,6 +103,49 @@ func collectDoctorPayload() (*doctorPayload, error) {
 	return collectDoctorPayloadWithContext(context.Background())
 }
 
+func collectTunnelDoctorPayload(ctx context.Context, tunnelID string) (*tunnelDoctorPayload, error) {
+	sess, err := findSession(tunnelID)
+	if err != nil {
+		return nil, err
+	}
+	ensureSessionPublicPort(ctx, sess)
+
+	snapshot := classifySession(*sess, true)
+	endpoint := endpointLabel(sess.Protocol, sess.Host, sess.SealosHost, sess.PublicPort)
+	payload := &tunnelDoctorPayload{
+		TunnelID:           sess.TunnelID,
+		Status:             snapshot.Status,
+		Protocol:           valueOr(sess.Protocol, "https"),
+		Endpoint:           endpoint,
+		LocalTarget:        "localhost:" + valueOr(sess.LocalPort, "unknown"),
+		Mode:               valueOr(sess.Mode, "foreground"),
+		Namespace:          sess.Namespace,
+		ProcessAlive:       snapshot.ProcessAlive,
+		LocalPortReachable: snapshot.LocalPortReachable,
+	}
+
+	payload.Checks = append(payload.Checks,
+		doctorCheck{Name: "session", Status: "ok", Detail: "local session record exists"},
+		ownerDoctorCheck(*sess, snapshot.ProcessAlive),
+		localPortDoctorCheck(*sess, snapshot.LocalPortReachable),
+	)
+
+	remoteCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	remote, err := collectRemoteDiagnosticsWithContext(remoteCtx, *sess)
+	cancel()
+	if err != nil {
+		payload.Checks = append(payload.Checks, doctorCheck{Name: "remote", Status: "warn", Detail: err.Error()})
+		payload.Warnings = append(payload.Warnings, fmt.Sprintf("remote diagnostics unavailable: %v", err))
+	} else {
+		payload.Remote = remote
+		payload.Checks = append(payload.Checks, remoteDoctorChecks(remote)...)
+		payload.Warnings = append(payload.Warnings, remote.Warnings...)
+	}
+
+	payload.Suggestions = tunnelDoctorSuggestions(*sess, payload)
+	return payload, nil
+}
+
 func collectDoctorPayloadWithContext(ctx context.Context) (*doctorPayload, error) {
 	status, err := collectStatus()
 	if err != nil {
@@ -258,3 +342,151 @@ func printDoctor(cmd *cobra.Command, payload *doctorPayload) {
 		fmt.Fprintln(out, "No issues detected from local diagnostics.")
 	}
 }
+
+func printTunnelDoctor(cmd *cobra.Command, payload *tunnelDoctorPayload) {
+	out := cmd.OutOrStdout()
+
+	fmt.Fprintln(out, "Sealtun Tunnel Doctor")
+	fmt.Fprintf(out, "  Tunnel ID: %s\n", payload.TunnelID)
+	fmt.Fprintf(out, "  Status: %s\n", payload.Status)
+	fmt.Fprintf(out, "  Protocol: %s\n", payload.Protocol)
+	fmt.Fprintf(out, "  Endpoint: %s\n", valueOr(payload.Endpoint, "-"))
+	fmt.Fprintf(out, "  Local target: %s\n", payload.LocalTarget)
+	fmt.Fprintf(out, "  Mode: %s\n", valueOr(payload.Mode, "unknown"))
+	fmt.Fprintf(out, "  Namespace: %s\n", valueOr(payload.Namespace, "unknown"))
+
+	if len(payload.Checks) > 0 {
+		fmt.Fprintln(out, "")
+		fmt.Fprintln(out, "Checks")
+		for _, check := range payload.Checks {
+			fmt.Fprintf(out, "  - %s: %s", check.Name, check.Status)
+			if check.Detail != "" {
+				fmt.Fprintf(out, " (%s)", check.Detail)
+			}
+			fmt.Fprintln(out)
+		}
+	}
+
+	if len(payload.Suggestions) > 0 {
+		fmt.Fprintln(out, "")
+		fmt.Fprintln(out, "Suggestions")
+		for _, suggestion := range payload.Suggestions {
+			fmt.Fprintf(out, "  - %s\n", suggestion)
+		}
+	}
+
+	if len(payload.Warnings) > 0 {
+		fmt.Fprintln(out, "")
+		fmt.Fprintln(out, "Warnings")
+		for _, warning := range payload.Warnings {
+			fmt.Fprintf(out, "  - %s\n", warning)
+		}
+	}
+}
+
+func checkStatus(ok bool) string {
+	if ok {
+		return "ok"
+	}
+	return "warn"
+}
+
+func ownerDoctorCheck(sess session.TunnelSession, alive bool) doctorCheck {
+	status := checkStatus(alive)
+	if sess.ConnectionState == session.ConnectionStateStopped {
+		status = "skip"
+	}
+	return doctorCheck{Name: "owner", Status: status, Detail: ownerCheckDetail(sess, alive)}
+}
+
+func ownerCheckDetail(sess session.TunnelSession, alive bool) string {
+	if alive {
+		return "owner process is alive"
+	}
+	if sess.ConnectionState == session.ConnectionStateStopped {
+		return "tunnel is stopped"
+	}
+	if sess.Mode == "daemon" {
+		return "local daemon is not running"
+	}
+	return "recorded process is not running"
+}
+
+func localPortDoctorCheck(sess session.TunnelSession, reachable bool) doctorCheck {
+	status := checkStatus(reachable)
+	if sess.ConnectionState == session.ConnectionStateStopped {
+		status = "skip"
+	}
+	return doctorCheck{Name: "local-port", Status: status, Detail: localPortCheckDetail(sess, reachable)}
+}
+
+func localPortCheckDetail(sess session.TunnelSession, reachable bool) string {
+	if reachable {
+		return "local target accepts TCP connections"
+	}
+	if strings.TrimSpace(sess.LocalPort) == "" {
+		return "local port is missing from the session"
+	}
+	if sess.ConnectionState == session.ConnectionStateStopped {
+		return "not checked because the tunnel is stopped"
+	}
+	return fmt.Sprintf("localhost:%s is not reachable", sess.LocalPort)
+}
+
+func remoteDoctorChecks(remote *k8s.TunnelDiagnostics) []doctorCheck {
+	if remote == nil {
+		return nil
+	}
+	deploymentStatus := checkStatus(remote.Deployment.Exists && remote.Deployment.ReadyReplicas > 0)
+	if remote.Deployment.Exists && remote.Deployment.DesiredReplicas == 0 {
+		deploymentStatus = "skip"
+	}
+	checks := []doctorCheck{
+		{Name: "deployment", Status: deploymentStatus, Detail: fmt.Sprintf("%d/%d ready", remote.Deployment.ReadyReplicas, remote.Deployment.DesiredReplicas)},
+		{Name: "service", Status: checkStatus(remote.Service.Exists), Detail: valueOr(strings.Join(remote.Service.Ports, ", "), "no ports reported")},
+	}
+	if remote.Ingress.Exists {
+		checks = append(checks, doctorCheck{Name: "ingress", Status: "ok", Detail: strings.Join(remote.Ingress.Hosts, ", ")})
+	} else {
+		checks = append(checks, doctorCheck{Name: "ingress", Status: "warn", Detail: "missing"})
+	}
+	if remote.Certificate != nil {
+		status := checkStatus(remote.Certificate.Exists && remote.Certificate.Ready)
+		checks = append(checks, doctorCheck{Name: "certificate", Status: status, Detail: certificateDoctorDetail(remote.Certificate)})
+	}
+	return checks
+}
+
+func certificateDoctorDetail(cert *k8s.CertificateDiagnostics) string {
+	if cert == nil || !cert.Exists {
+		return "missing"
+	}
+	if cert.Ready {
+		return "ready"
+	}
+	return "not ready"
+}
+
+func tunnelDoctorSuggestions(sess session.TunnelSession, payload *tunnelDoctorPayload) []string {
+	suggestions := []string{}
+	if payload.Status == "stopped" {
+		suggestions = append(suggestions, fmt.Sprintf("run `sealtun start %s` to resume the tunnel", sess.TunnelID))
+		return suggestions
+	}
+	if !payload.ProcessAlive && sess.Mode == "daemon" {
+		suggestions = append(suggestions, "run `sealtun status` to check the daemon, then restart the tunnel if needed")
+	}
+	if !payload.LocalPortReachable && strings.TrimSpace(sess.LocalPort) != "" && payload.Status != "stopped" {
+		suggestions = append(suggestions, fmt.Sprintf("start the local service on localhost:%s, then rerun `sealtun doctor %s`", sess.LocalPort, sess.TunnelID))
+	}
+	if payload.Remote == nil {
+		suggestions = append(suggestions, fmt.Sprintf("run `sealtun inspect %s --remote` after login to see Kubernetes resource details", sess.TunnelID))
+	}
+	if sess.CustomDomain != "" {
+		suggestions = append(suggestions, fmt.Sprintf("run `sealtun domain doctor %s` to verify DNS, Ingress, and certificate status", sess.TunnelID))
+	}
+	if len(suggestions) == 0 {
+		suggestions = append(suggestions, "no immediate action suggested")
+	}
+	return suggestions
+}