feat(dev): 开发体验改进与跨平台支持

- Makefile: dev/dev-api 自动检测并启动 PostgreSQL，非 Linux 自动构建网关镜像
- 新增 scripts/dev-backend.sh 后端热重载开发脚本
- entry.go: 能力推导优先读取 image.lock 显式声明，解决重建后 template_image_ref 未同步问题
- sshproxy/resolver: 跨平台容器地址解析（macOS/Windows 用端口映射替代直接 IP）
- cloudclaude: 新增 cold_promoter 冷文件晋升逻辑
- web/admin: hosts 列表优先显示进行中任务状态
- runtime: worker 与 runtime_service 适配调整

Author: ZaneL1u

Makefile

@@ -7,25 +7,39 @@ DEV_COMPOSE := docker compose -f deploy/compose/control-plane.dev.yml
 
 # ── Development ──────────────────────────────────────────────
 
-dev: ## Start backend + frontend (requires PostgreSQL running)
+dev: ## Start backend + frontend (auto-starts PostgreSQL if needed)
 	@echo "Starting control-plane + admin frontend..."
 	@echo "  API  → http://$(CONTROL_PLANE_ADDR)"
 	@echo "  Web  → http://localhost:5173"
 	@echo "  Agent → embedded (in-process)"
 	@echo ""
 	@mkdir -p .data
-	@trap 'kill 0' EXIT; \
-		HOST_AGENT_MODE=embedded DATA_DIR=$(CURDIR)/.data go run ./cmd/control-plane & \
-		cd web/admin && pnpm dev & \
+	@# Auto-start PostgreSQL if not running
+	@nc -z 127.0.0.1 $(POSTGRES_PORT) > /dev/null 2>&1 || \
+		{ echo "PostgreSQL not running, starting it now..."; $(MAKE) db; }
+	@# On macOS / Windows, ensure gateway sidecar image exists (ContainerProxyProvider needs it)
+	@if [ "$$(uname -s)" != "Linux" ]; then \
+		if ! docker images $(GATEWAY_IMAGE) --format '{{.Repository}}:{{.Tag}}' 2>/dev/null | grep -qF '$(GATEWAY_IMAGE)'; then \
+			echo "Non-Linux host: gateway image not found, building $(GATEWAY_IMAGE)..."; \
+			$(MAKE) gateway-image; \
+		fi; \
+	fi
+	@trap 'kill $$CP_PID $$VITE_PID 2>/dev/null; wait' INT EXIT; \
+		bash scripts/dev-backend.sh & CP_PID=$$!; \
+		cd web/admin && pnpm dev & VITE_PID=$$!; \
 		wait
 
-dev-api: ## Start backend only (with embedded host-agent)
+dev-api: ## Start backend only with hot reload (auto-starts PostgreSQL)
 	@mkdir -p .data
-	HOST_AGENT_MODE=embedded DATA_DIR=$(CURDIR)/.data go run ./cmd/control-plane
+	@nc -z 127.0.0.1 $(POSTGRES_PORT) > /dev/null 2>&1 || \
+		{ echo "PostgreSQL not running, starting it now..."; $(MAKE) db; }
+	@bash scripts/dev-backend.sh
 
 dev-web: ## Start frontend only
 	cd web/admin && pnpm dev
 
+dev-all: dev ## Alias for 'make dev' (PostgreSQL is auto-started)
+
 # ── Database ─────────────────────────────────────────────────
 
 db: ## Start PostgreSQL via Docker Compose
@@ -54,13 +68,15 @@ test-smoke: ## Run BATS bootstrap smoke tests
 # ── Images ────────────────────────────────────────────────────
 
 MANAGED_USER_TAG := $(shell grep '^image_name:' deploy/docker/managed-user/image.lock | cut -d' ' -f2)
+GATEWAY_IMAGE    := cloud-cli-proxy-sing-gateway:local
 
 user-image: ## Build managed-user image (cloud desktop)
 	docker build -t $(MANAGED_USER_TAG) -f deploy/docker/managed-user/Dockerfile .
 	@echo "Built: $(MANAGED_USER_TAG)"
 
 gateway-image: ## Build sing-box + iptables sidecar (required for macOS/Windows host-agent egress)
-	docker build -t cloud-cli-proxy-sing-gateway:local -f deploy/docker/sing-box-gateway/Dockerfile .
+	docker build -t $(GATEWAY_IMAGE) -f deploy/docker/sing-box-gateway/Dockerfile .
+	@echo "Built: $(GATEWAY_IMAGE)"
 
 # ── Build ────────────────────────────────────────────────────
 
@@ -117,8 +133,14 @@ release: ## Create and push release tag (usage make release VERSION=1.5.0)
 setup: ## First-time setup: install deps, copy .env
 	cd web/admin && pnpm install
 	@test -f .env || cp .env.example .env
-	@echo "Done. Edit .env if needed, then run: make db && make dev"
-	@echo "提示：在 macOS/Windows 上调试主机出口代理（sidecar 网关）前请先执行一次: make gateway-image"
+	@echo "Done. Edit .env if needed, then run: make dev"
+	@echo ""
+	@echo "常用命令:"
+	@echo "  make dev         一键启动 PostgreSQL + 后端 + 前端（推荐）"
+	@echo "  make dev-api     只启动后端（自动启动 PostgreSQL）"
+	@echo "  make dev-web     只启动前端"
+	@echo "  make db          只启动 PostgreSQL"
+	@echo "  make gateway-image  构建网关 sidecar 镜像（非 Linux 首次需执行）"
 
 # ── Utilities ────────────────────────────────────────────────
 

internal/cloudclaude/cold_promoter.go

@@ -0,0 +1,50 @@
+package cloudclaude
+
+import (
+	"context"
+	"io"
+	"sync/atomic"
+
+	"golang.org/x/crypto/ssh"
+)
+
+// ColdPromoter performs background promotion of cold files to hot.
+// Phase 37: Full implementation with inotify-based promotion is planned.
+// Currently a minimal stub so mount_strategy.go compiles on all platforms.
+type ColdPromoter struct {
+	connB    *ssh.Client
+	coldRoot string
+	hotRoot  string
+	logger   io.Writer
+	pidFile  string
+
+	promotionCount       atomic.Int64
+	promotionBytes       atomic.Int64
+	promotionFailedCount atomic.Int64
+}
+
+// NewColdPromoter creates a new ColdPromoter.
+func NewColdPromoter(connB *ssh.Client, coldRoot, hotRoot string, logger io.Writer, pidFile string) *ColdPromoter {
+	return &ColdPromoter{
+		connB:    connB,
+		coldRoot: coldRoot,
+		hotRoot:  hotRoot,
+		logger:   logger,
+		pidFile:  pidFile,
+	}
+}
+
+// Run starts the promotion loop.
+// Stub: Phase 37 will implement inotify watcher + rsync promotion.
+func (p *ColdPromoter) Run(ctx context.Context) {
+	<-ctx.Done()
+}
+
+// Wait waits for the promoter to finish.
+// Stub: Phase 37 will wait for the background goroutine to exit.
+func (p *ColdPromoter) Wait() {}
+
+// Stats returns promotion statistics.
+func (p *ColdPromoter) Stats() (count int, bytes int64, failed int) {
+	return int(p.promotionCount.Load()), p.promotionBytes.Load(), int(p.promotionFailedCount.Load())
+}

internal/cloudclaude/ssh.go

@@ -140,7 +140,7 @@ func ConnectAndRunClaudeV3(cfg SSHConfig, claudeArgs []string, cwd string,
 	// 退出码引用 cloudclaude.Exit* 命名常量（避开 v2.0 main.go ExitConfigError=4 /
 	// ExitInternalError=5 撞码；OAuthNotFound=6 / OAuthExpired=7）。
 	if mountCfg.ClaudeAccountID == "" {
-		fmt.Fprintln(mountCfg.Logger, "[!] gateway 未返回 claude_account_id，跳过 OAuth 过期检查（建议升级 gateway 至 v3.0）")
+		fmt.Fprintln(mountCfg.Logger, "[!] 未配置 Claude Account 绑定，跳过 OAuth 过期检查（不影响正常使用）")
 	} else {
 		status, oauthErr := CheckOAuthCredentials(connA, mountCfg.ClaudeAccountID)
 		if oauthErr != nil {

internal/controlplane/app/app.go

@@ -156,6 +156,8 @@ func New(ctx context.Context, cfg Config) (*App, error) {
 		AdminEvents:         repo,
 		EventRecorder:       repo,
 		EntryStore:     repo,
+		EntryBaseURL:   "",
+		ImageLockPath:  runtime.DefaultImageLockPath,
 		UserHosts:      repo,
 		SSHKeys:        repo,
 	})

internal/controlplane/http/entry.go

@@ -12,6 +12,7 @@ import (
 	"github.com/jackc/pgx/v5"
 	"golang.org/x/crypto/bcrypt"
 
+	"github.com/zanel1u/cloud-cli-proxy/internal/runtime"
 	"github.com/zanel1u/cloud-cli-proxy/internal/store/repository"
 )
 
@@ -34,8 +35,18 @@ const v3CapBaseline = "v3.0.0"
 //  1. 整体 trim 空白；
 //  2. 取最后一个 ":" 之后的 tag；若不存在 ":"，整串视为 tag；
 //  3. 再对 tag trim 空白（兼容异常配置）；
-//  4. supports_mergerfs = (tag == v3CapBaseline)。
-func deriveEntryCapabilities(templateImageRef string) (imageVersion string, supportsMergerfs bool) {
+//  4. supports_mergerfs = imageLockSupportsMergerfs || (tag == v3CapBaseline)。
+//     imageLockSupportsMergerfs 来自 image.lock 的显式声明，优先于 tag 推导，
+//     用于解决重建主机后数据库 template_image_ref 未同步更新的问题。
+func deriveEntryCapabilities(templateImageRef string, imageLockSupportsMergerfs bool) (imageVersion string, supportsMergerfs bool) {
+	if imageLockSupportsMergerfs {
+		tag := strings.TrimSpace(templateImageRef)
+		if idx := strings.LastIndex(tag, ":"); idx != -1 {
+			tag = tag[idx+1:]
+		}
+		tag = strings.TrimSpace(tag)
+		return tag, true
+	}
 	tag := strings.TrimSpace(templateImageRef)
 	if idx := strings.LastIndex(tag, ":"); idx != -1 {
 		tag = tag[idx+1:]
@@ -46,13 +57,14 @@ func deriveEntryCapabilities(templateImageRef string) (imageVersion string, supp
 }
 
 type EntryHandler struct {
-	logger  *slog.Logger
-	store   EntryStore
-	baseURL string
+	logger        *slog.Logger
+	store         EntryStore
+	baseURL       string
+	imageLockPath string
 }
 
-func NewEntryHandler(logger *slog.Logger, store EntryStore, baseURL string) *EntryHandler {
-	return &EntryHandler{logger: logger, store: store, baseURL: baseURL}
+func NewEntryHandler(logger *slog.Logger, store EntryStore, baseURL, imageLockPath string) *EntryHandler {
+	return &EntryHandler{logger: logger, store: store, baseURL: baseURL, imageLockPath: imageLockPath}
 }
 
 func (h *EntryHandler) Script() nethttp.Handler {
@@ -197,9 +209,13 @@ func (h *EntryHandler) Auth() nethttp.Handler {
 			sshHost = sshHost[:idx]
 		}
 
-		// Phase 30 D-06/D-07：仅依据 template_image_ref 推导能力字段，
-		// 不访问 host-agent / Docker registry（D-04 维持 Phase 29 结论）。
-		imageVersion, supportsMergerfs := deriveEntryCapabilities(templateImageRef)
+		// Phase 30 D-06/D-07：依据 template_image_ref + image.lock 显式声明推导能力字段。
+		// image.lock 的 supports_mergerfs 优先，解决重建主机后 DB 字段未同步问题。
+		var imageLockSupportsMergerfs bool
+		if spec, specErr := runtime.LoadRuntimeSpec(h.imageLockPath); specErr == nil {
+			imageLockSupportsMergerfs = spec.SupportsMergerfs
+		}
+		imageVersion, supportsMergerfs := deriveEntryCapabilities(templateImageRef, imageLockSupportsMergerfs)
 
 		resp := map[string]any{
 			"ssh_user":          user.Username,

internal/controlplane/http/entry_auth_test.go

@@ -71,7 +71,7 @@ func mustBcrypt(t *testing.T, password string) string {
 
 func doAuth(t *testing.T, store EntryStore, username, password string) (*httptest.ResponseRecorder, map[string]any) {
 	t.Helper()
-	handler := NewEntryHandler(slog.Default(), store, "").Auth()
+	handler := NewEntryHandler(slog.Default(), store, "", "").Auth()
 	body, _ := json.Marshal(map[string]string{"password": password})
 	req := httptest.NewRequest(nethttp.MethodPost, "/v1/entry/"+username+"/auth", bytes.NewReader(body))
 	req.Host = "gateway.example.com"

internal/controlplane/http/entry_caps_test.go

@@ -4,14 +4,15 @@ import "testing"
 
 // TestDeriveEntryCapabilities 覆盖 Phase 30 D-06/D-07：
 // - image_version 来自 template_image_ref 最后一个 ":" 后的 tag（无 ":" 则整串），仅 trim 空白；
-// - supports_mergerfs 当且仅当 image_version == "v3.0.0" 时为 true；
-// - 本阶段禁止引入任何额外的 tag 对照表。
+// - supports_mergerfs = imageLockSupportsMergerfs || (image_version == "v3.0.0")；
+// - image.lock 显式声明为 true 时优先覆盖 tag 推导，解决重建后 DB 字段未同步问题。
 func TestDeriveEntryCapabilities(t *testing.T) {
 	tests := []struct {
-		name            string
-		ref             string
-		wantVersion     string
-		wantMergerfs    bool
+		name                      string
+		ref                       string
+		imageLockSupportsMergerfs bool
+		wantVersion               string
+		wantMergerfs              bool
 	}{
 		{
 			name:         "v3.0.0 tag unlocks mergerfs",
@@ -55,10 +56,24 @@ func TestDeriveEntryCapabilities(t *testing.T) {
 			wantVersion:  "v3.0.0",
 			wantMergerfs: true,
 		},
+		{
+			name:                      "image.lock true overrides old tag",
+			ref:                       "ghcr.io/example/cloud-claude:v2.0.0",
+			imageLockSupportsMergerfs: true,
+			wantVersion:               "v2.0.0",
+			wantMergerfs:              true,
+		},
+		{
+			name:                      "image.lock true works with any ref",
+			ref:                       "cloudclaude-image",
+			imageLockSupportsMergerfs: true,
+			wantVersion:               "cloudclaude-image",
+			wantMergerfs:              true,
+		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			version, mergerfs := deriveEntryCapabilities(tc.ref)
+			version, mergerfs := deriveEntryCapabilities(tc.ref, tc.imageLockSupportsMergerfs)
 			if version != tc.wantVersion {
 				t.Errorf("image_version = %q, want %q", version, tc.wantVersion)
 			}

internal/controlplane/http/user_hosts.go

@@ -121,17 +121,10 @@ func (h *UserHostsHandler) Get() nethttp.Handler {
 				host = host[:idx]
 			}
 			baseURL := fmt.Sprintf("%s://%s", scheme, r.Host)
-			sshTarget := detail.Host.ShortID
-			if sshTarget == "" {
-				sshTarget = user.ShortID
-			}
-			if user.ShortID != "" || sshTarget != "" {
-				entryID := detail.Host.ShortID
-				if entryID == "" {
-					entryID = user.ShortID
-				}
+			sshTarget := user.Username
+			if sshTarget != "" {
 				resp.ConnectionInfo = &repository.ConnectionInfo{
-					CurlCommand: fmt.Sprintf("curl -sSL %s/entry/%s | bash", baseURL, entryID),
+					CurlCommand: fmt.Sprintf("curl -sSL %s/entry/%s | bash", baseURL, sshTarget),
 					SSHCommand:  fmt.Sprintf("ssh %s@%s -p 2222", sshTarget, host),
 					SSHPort:     2222,
 					VNCURL:      fmt.Sprintf("%s/v1/user/hosts/%s/vnc/vnc.html", baseURL, detail.Host.ID),

internal/network/container_proxy_provider.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"time"
 )
@@ -98,8 +99,12 @@ func (p *ContainerProxyProvider) PrepareHost(ctx context.Context, spec HostNetwo
 		return fmt.Errorf("gateway: connect worker to network: %w", err)
 	}
 
-	// 断开 Worker 原来的 bridge 网络，让隔离网络成为唯一出口
-	_ = exec.CommandContext(ctx, "docker", "network", "disconnect", "-f", "bridge", workerName).Run()
+	// 断开 Worker 原来的 bridge 网络，让隔离网络成为唯一出口。
+	// macOS/Windows: 保留 bridge 网络，因为 Docker Desktop 宿主机无法直接路由到
+	// 容器内部 IP，SSH 端口映射依赖 bridge 网络存活。
+	if runtime.GOOS == "linux" {
+		_ = exec.CommandContext(ctx, "docker", "network", "disconnect", "-f", "bridge", workerName).Run()
+	}
 
 	// 等待隔离网络的接口就绪（disconnect 后可能有短暂延迟）
 	time.Sleep(1 * time.Second)

internal/runtime/runtime_service.go

@@ -27,6 +27,7 @@ type RuntimeSpec struct {
 	DefaultUser        string
 	HomeMount          string
 	RebuildModeDefault string
+	SupportsMergerfs   bool
 }
 
 // QueueHostActionRepo 是 Service 在排队 host 操作时需要的仓储接口。
@@ -251,6 +252,7 @@ func LoadRuntimeSpec(path string) (RuntimeSpec, error) {
 		DefaultUser:        values["default_user"],
 		HomeMount:          values["home_mount"],
 		RebuildModeDefault: firstNonEmpty(values["rebuild_mode_default"], defaultRebuildMode),
+		SupportsMergerfs:   values["supports_mergerfs"] == "true",
 	}
 
 	if spec.ImageName == "" {