feat(cloudflare): 新增全局托管开关并发布 v1.8.0

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.8.0] - 2026-09-30
+
+### 新增
+
+- **Cloudflare 隧道全局托管开关**：页面顶部新增「全局托管」开关：
+  - 关闭时立即停止所有隧道进程，应用重启后不再自动拉起；单条隧道的「启动」按钮同时禁用
+  - 开启时只恢复标记了 `auto_start` 的隧道，其余保持停止
+  - 只影响本机 cloudflared 进程托管，不删除本地配置、凭据、云端隧道或 DNS 记录
+- 新增 `cf_settings.enabled` 字段（迁移 `034`）与 `POST /api/cloudflare/enabled` 接口
+
+### 变更
+
+- 版本号提升到 1.8.0；`AgentVersion` 保持 **0.14.1**
+
+### 测试
+
+- 新增「全局停用时拒绝启动」单元测试
+- `go test ./...`、`go vet ./...`、`npm run typecheck`、`npm test`、`npm run build` 通过
+
 ## [v1.7.0] - 2026-09-28
 
 ### 新增

VERSION

@@ -1 +1 @@
-1.7.0
+1.8.0

docs/README.md

@@ -1,7 +1,7 @@
 # Fonu 文档索引
 
 > 维护约定：新增方案 / 审查文档时在下方登记；方案落地后在「状态」列标注实施结果，并给已被推翻的描述加时效说明。
-> 最近更新：2026-09-28（v1.7.0）
+> 最近更新：2026-09-30（v1.8.0）
 
 ## 方案与设计（本目录）
 

docs/system-upgrade.md

@@ -238,16 +238,16 @@ FONU_VERSION=<旧版本> docker compose up -d --no-deps --force-recreate fonu
 
 ## 10. 在线升级验证
 
-示例页面用于验证升级结果。v1.7.0 的验证流程：
+示例页面用于验证升级结果。v1.8.0 的验证流程：
 
 1. 确认当前线上实例为 v1.3.0，且 `fonu-updater` sidecar 已运行。
-2. 确认远端 `main` 分支的 `VERSION` 为 `1.7.0`。
+2. 确认远端 `main` 分支的 `VERSION` 为 `1.8.0`。
 3. 在侧栏看到「一键升级」后点击并确认。
 4. 等待升级弹窗显示成功，页面自动刷新。
 5. 打开侧栏「示例页面」，确认：
    - 页面路由为 `/example`；
-   - 页面显示的版本为 `1.7.0`；
-   - 页面显示验证标识 `v1.7.0-example-page`；
+   - 页面显示的版本为 `1.8.0`；
+   - 页面显示验证标识 `v1.8.0-example-page`；
    - 页面显示独立的「本次升级验证」区块；
    - 「升级验证」显示为「通过」。
 

internal/api/cloudflare_handler.go

@@ -207,6 +207,22 @@ func (h *CloudflareHandler) TestToken(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "message": message})
 }
 
+func (h *CloudflareHandler) SetEnabled(w http.ResponseWriter, r *http.Request) {
+	var request struct {
+		Enabled bool `json:"enabled"`
+	}
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10)).Decode(&request); err != nil {
+		writeError(r, w, http.StatusBadRequest, "请求格式无效")
+		return
+	}
+	settings, err := h.svc.SetEnabled(r.Context(), request.Enabled)
+	if err != nil {
+		writeError(r, w, http.StatusBadGateway, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, settings)
+}
+
 func (h *CloudflareHandler) DownloadBinary(w http.ResponseWriter, r *http.Request) {
 	var request struct {
 		Mirror string `json:"mirror"`

internal/api/router.go

@@ -209,6 +209,7 @@ func newRouterWithSpecs(deps Deps) (http.Handler, []routeSpec) {
 		protect("GET /api/cloudflare/settings", cf.AppSettings)
 		protect("PUT /api/cloudflare/settings", cf.SaveAppSettings)
 		protect("POST /api/cloudflare/settings/test", cf.TestToken)
+		protect("POST /api/cloudflare/enabled", cf.SetEnabled)
 		protect("GET /api/cloudflare/ingress-candidates", cf.IngressCandidates)
 	}
 

internal/cloudflared/model.go

@@ -74,6 +74,7 @@ type CreateInput struct {
 // AppSettings 是模块级配置；默认 token 只回显掩码，不返回明文。
 type AppSettings struct {
 	AccountID              string          `json:"account_id"`
+	Enabled                bool            `json:"enabled"`
 	DefaultTokenConfigured bool            `json:"default_token_configured"`
 	DefaultTokenMasked     string          `json:"default_token_masked"`
 	APITokenConfigured     bool            `json:"api_token_configured"`
@@ -85,6 +86,7 @@ type AppSettings struct {
 // AppSettingsInput 是保存应用配置的入参；Token 留空表示保留原值。
 type AppSettingsInput struct {
 	AccountID string          `json:"account_id"`
+	Enabled   *bool           `json:"enabled,omitempty"`
 	Token     string          `json:"token"`
 	APIToken  string          `json:"api_token"`
 	Mirror    string          `json:"mirror"`

internal/cloudflared/service.go

@@ -181,6 +181,13 @@ func (s *Service) Delete(ctx context.Context, id int64) error {
 }
 
 func (s *Service) Start(ctx context.Context, id int64) (Tunnel, error) {
+	settings, err := s.store.GetSettingsRaw(ctx)
+	if err != nil {
+		return Tunnel{}, err
+	}
+	if !settings.Enabled {
+		return Tunnel{}, fmt.Errorf("Cloudflare 隧道全局已停用，请先在页面顶部重新启用")
+	}
 	tunnel, err := s.store.Get(ctx, id)
 	if err != nil {
 		return Tunnel{}, err
@@ -229,7 +236,7 @@ func (s *Service) AppSettings(ctx context.Context) (AppSettings, error) {
 	if err != nil {
 		return AppSettings{}, err
 	}
-	out := AppSettings{AccountID: row.AccountID, Mirror: row.Mirror, Network: row.Network}
+	out := AppSettings{AccountID: row.AccountID, Enabled: row.Enabled, Mirror: row.Mirror, Network: row.Network}
 	if row.TokenEnc != "" {
 		out.DefaultTokenConfigured = true
 		if plain, err := s.secretBox.Decrypt(row.TokenEnc); err == nil {
@@ -255,6 +262,10 @@ func (s *Service) SaveAppSettings(ctx context.Context, in AppSettingsInput) (App
 	if accountID == "" {
 		accountID = row.AccountID
 	}
+	enabled := row.Enabled
+	if in.Enabled != nil {
+		enabled = *in.Enabled
+	}
 	tokenEnc := row.TokenEnc
 	apiTokenEnc := row.APITokenEnc
 	if apiToken := strings.TrimSpace(in.APIToken); apiToken != "" {
@@ -274,12 +285,44 @@ func (s *Service) SaveAppSettings(ctx context.Context, in AppSettingsInput) (App
 	if strings.TrimSpace(network.TransportProtocol) == "" {
 		network = row.Network
 	}
-	if err := s.store.SaveSettings(ctx, accountID, tokenEnc, apiTokenEnc, mirror, network); err != nil {
+	if err := s.store.SaveSettings(ctx, accountID, enabled, tokenEnc, apiTokenEnc, mirror, network); err != nil {
 		return AppSettings{}, err
 	}
 	return s.AppSettings(ctx)
 }
 
+// SetEnabled 切换全局托管开关；关闭时停止所有隧道，开启时恢复 auto_start 的隧道。
+func (s *Service) SetEnabled(ctx context.Context, enabled bool) (AppSettings, error) {
+	row, err := s.store.GetSettingsRaw(ctx)
+	if err != nil {
+		return AppSettings{}, err
+	}
+	if err := s.store.SaveSettings(ctx, row.AccountID, enabled, row.TokenEnc, row.APITokenEnc, row.Mirror, row.Network); err != nil {
+		return AppSettings{}, err
+	}
+	if enabled {
+		s.StartAuto(ctx)
+	} else {
+		s.StopAll(ctx)
+	}
+	return s.AppSettings(ctx)
+}
+
+// StopAll 停止所有隧道进程，但保留配置、凭据与云端隧道。
+func (s *Service) StopAll(ctx context.Context) {
+	tunnels, err := s.store.List(ctx)
+	if err != nil {
+		s.logger.Warn("读取 Cloudflare 隧道失败", "error", err.Error())
+		return
+	}
+	for _, tunnel := range tunnels {
+		if err := s.manager.Stop(tunnel.ID); err != nil {
+			s.logger.Warn("停止 Cloudflare 隧道失败", "tunnel_id", tunnel.ID, "error", err.Error())
+		}
+		_ = s.store.SetRuntime(ctx, tunnel.ID, "stopped", "", 0)
+	}
+}
+
 func (s *Service) applyDefaultNetwork(ctx context.Context, network NetworkSettings) NetworkSettings {
 	if strings.TrimSpace(network.TransportProtocol) != "" {
 		return network
@@ -438,6 +481,14 @@ func (s *Service) IngressCandidates(ctx context.Context) ([]string, error) {
 
 // StartAuto 在应用启动时拉起标记了 auto_start 的隧道。
 func (s *Service) StartAuto(ctx context.Context) {
+	settings, err := s.store.GetSettingsRaw(ctx)
+	if err != nil {
+		s.logger.Warn("读取 Cloudflare 配置失败", "error", err.Error())
+		return
+	}
+	if !settings.Enabled {
+		return
+	}
 	tunnels, err := s.store.List(ctx)
 	if err != nil {
 		s.logger.Warn("读取 Cloudflare 隧道失败", "error", err.Error())

internal/cloudflared/settings_test.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"log/slog"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/fonu/fonu/internal/config"
@@ -41,3 +42,35 @@ func TestAppSettingsAccountAndAPIToken(t *testing.T) {
 		t.Fatalf("cloudflareAPI 构造失败：%v %#v", err, api)
 	}
 }
+
+func TestSetEnabledBlocksStart(t *testing.T) {
+	dir := t.TempDir()
+	conn, err := db.Open(filepath.Join(dir, "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	if err := db.Migrate(context.Background(), conn, filepath.Join("..", "..", "migrations")); err != nil {
+		t.Fatal(err)
+	}
+	box, err := secret.NewBox("cloudflared-enabled-test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	svc := NewService(config.Config{DataDir: dir}, NewStore(conn), box, slog.New(slog.NewTextHandler(io.Discard, nil)), nil)
+
+	settings, err := svc.SetEnabled(context.Background(), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if settings.Enabled {
+		t.Fatal("全局托管应为停用")
+	}
+	if _, err := svc.Start(context.Background(), 1); err == nil || !strings.Contains(err.Error(), "全局已停用") {
+		t.Fatalf("全局停用时启动应被拒绝：%v", err)
+	}
+	settings, err = svc.SetEnabled(context.Background(), true)
+	if err != nil || !settings.Enabled {
+		t.Fatalf("重新启用失败：%v %#v", err, settings)
+	}
+}

internal/cloudflared/store.go

@@ -98,6 +98,7 @@ func (s *Store) SetRuntime(ctx context.Context, id int64, status, lastError stri
 // settingsRow 是应用配置的原始行；TokenEnc 只在 Service 内部解密，不直接回给前端。
 type settingsRow struct {
 	AccountID   string
+	Enabled     bool
 	TokenEnc    string
 	APITokenEnc string
 	Mirror      string
@@ -106,29 +107,30 @@ type settingsRow struct {
 
 func (s *Store) GetSettingsRaw(ctx context.Context) (settingsRow, error) {
 	var accountID, tokenEnc, apiTokenEnc, mirror, networkJSON string
+	var enabled int
 	err := s.db.QueryRowContext(ctx, `
-		SELECT COALESCE(account_id, ''), COALESCE(default_token_enc, ''), COALESCE(api_token_enc, ''),
+		SELECT COALESCE(account_id, ''), COALESCE(enabled, 1), COALESCE(default_token_enc, ''), COALESCE(api_token_enc, ''),
 		       COALESCE(mirror, 'official'), COALESCE(network_json, '{}')
 		FROM cf_settings WHERE id = 1
-	`).Scan(&accountID, &tokenEnc, &apiTokenEnc, &mirror, &networkJSON)
+	`).Scan(&accountID, &enabled, &tokenEnc, &apiTokenEnc, &mirror, &networkJSON)
 	if errors.Is(err, sql.ErrNoRows) {
-		return settingsRow{Mirror: "official", Network: DefaultNetworkSettings()}, nil
+		return settingsRow{Enabled: true, Mirror: "official", Network: DefaultNetworkSettings()}, nil
 	}
 	if err != nil {
 		return settingsRow{}, err
 	}
-	row := settingsRow{AccountID: accountID, TokenEnc: tokenEnc, APITokenEnc: apiTokenEnc, Mirror: mirror, Network: DefaultNetworkSettings()}
+	row := settingsRow{AccountID: accountID, Enabled: enabled == 1, TokenEnc: tokenEnc, APITokenEnc: apiTokenEnc, Mirror: mirror, Network: DefaultNetworkSettings()}
 	_ = json.Unmarshal([]byte(networkJSON), &row.Network)
 	return row, nil
 }
 
-func (s *Store) SaveSettings(ctx context.Context, accountID, tokenEnc, apiTokenEnc, mirror string, network NetworkSettings) error {
+func (s *Store) SaveSettings(ctx context.Context, accountID string, enabled bool, tokenEnc, apiTokenEnc, mirror string, network NetworkSettings) error {
 	networkJSON, _ := json.Marshal(network)
 	_, err := s.db.ExecContext(ctx, `
 		UPDATE cf_settings
-		SET account_id = ?, default_token_enc = ?, api_token_enc = ?, mirror = ?, network_json = ?, updated_at = datetime('now')
+		SET account_id = ?, enabled = ?, default_token_enc = ?, api_token_enc = ?, mirror = ?, network_json = ?, updated_at = datetime('now')
 		WHERE id = 1
-	`, accountID, tokenEnc, apiTokenEnc, mirror, string(networkJSON))
+	`, accountID, boolInt(enabled), tokenEnc, apiTokenEnc, mirror, string(networkJSON))
 	return err
 }
 

migrations/034_cf_global_enabled.sql

@@ -0,0 +1,2 @@
+-- Cloudflare 隧道全局托管开关：关闭后停止所有隧道，且应用重启不再自动拉起。
+ALTER TABLE cf_settings ADD COLUMN enabled INTEGER NOT NULL DEFAULT 1;

web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "fonu-web",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fonu-web",
-      "version": "1.7.0",
+      "version": "1.8.0",
       "dependencies": {
         "@codemirror/commands": "^6.11.1",
         "@codemirror/lang-javascript": "^6.2.5",

web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fonu-web",
   "private": true,
-  "version": "1.7.0",
+  "version": "1.8.0",
   "packageManager": "npm@10.9.4",
   "type": "module",
   "scripts": {

web/src/api/client.ts

@@ -517,4 +517,9 @@ export const api = {
       method: 'POST',
       body: JSON.stringify({ account_id: accountId, token, kind }),
     }, 60_000),
+  setCfEnabled: (enabled: boolean) =>
+    request<CfAppSettings>('/api/cloudflare/enabled', {
+      method: 'POST',
+      body: JSON.stringify({ enabled }),
+    }),
 }

web/src/api/types.ts

@@ -1102,6 +1102,7 @@ export interface CfTunnelPayload {
 
 export interface CfAppSettings {
   account_id: string
+  enabled: boolean
   default_token_configured: boolean
   default_token_masked: string
   api_token_configured: boolean
@@ -1112,6 +1113,7 @@ export interface CfAppSettings {
 
 export interface CfAppSettingsInput {
   account_id: string
+  enabled?: boolean
   token: string
   api_token: string
   mirror: string

web/src/views/CloudflareView.vue

@@ -6,6 +6,14 @@
     </template>
   </PageHeader>
 
+  <div class="cf-global" :class="{ 'cf-global--off': !appSettings.enabled }">
+    <div class="cf-global__text">
+      <strong>全局托管</strong>
+      <span>{{ appSettings.enabled ? '已启用：隧道进程由 Fonu 托管，auto_start 的隧道会在应用启动时恢复' : '已停用：所有隧道已停止，应用重启后也不会自动拉起' }}</span>
+    </div>
+    <n-switch :value="appSettings.enabled" :loading="globalLoading" @update:value="toggleGlobal" />
+  </div>
+
   <n-alert v-if="binaryVersion" type="info" :bordered="false" class="cf-alert">
     已安装：<span class="mono">{{ binaryVersion }}</span>
   </n-alert>
@@ -26,7 +34,7 @@
       <div class="cf-row__actions">
         <n-button size="small" @click="openDetail(item)">详情</n-button>
         <n-button size="small" @click="openEdit(item)">编辑</n-button>
-        <n-button v-if="item.status !== 'connected' && item.status !== 'starting'" size="small" type="success" @click="startTunnel(item)">启动</n-button>
+        <n-button v-if="item.status !== 'connected' && item.status !== 'starting'" size="small" type="success" :disabled="!appSettings.enabled" @click="startTunnel(item)">启动</n-button>
         <n-button v-else size="small" type="warning" @click="stopTunnel(item)">停止</n-button>
         <n-button size="small" @click="restartTunnel(item)">重启</n-button>
         <n-popconfirm @positive-click="removeTunnel(item)">
@@ -178,6 +186,7 @@ const candidates = ref<string[]>([])
 const loading = ref(false)
 const saving = ref(false)
 const binaryLoading = ref(false)
+const globalLoading = ref(false)
 const settingsVisible = ref(false)
 const settingsLoading = ref(false)
 const settingsSaving = ref(false)
@@ -186,6 +195,7 @@ const tokenTestResult = ref('')
 const tokenTestOk = ref(false)
 const appSettings = ref<CfAppSettings>({
   account_id: '',
+  enabled: true,
   default_token_configured: false,
   default_token_masked: '',
   api_token_configured: false,
@@ -251,6 +261,20 @@ async function load() {
   }
 }
 
+async function toggleGlobal(value: boolean) {
+  globalLoading.value = true
+  try {
+    const result = await api.setCfEnabled(value)
+    appSettings.value = result
+    message.success(value ? '全局托管已启用' : '全局托管已停用，所有隧道已停止')
+    await load()
+  } catch (error) {
+    message.error(error instanceof Error ? error.message : '切换全局托管失败')
+  } finally {
+    globalLoading.value = false
+  }
+}
+
 async function loadBinary() {
   try {
     const result = await api.getCfBinary()
@@ -496,6 +520,20 @@ useVisibilityPolling(refreshDetail, 3000, { enabled: detailVisible })
 </script>
 
 <style scoped>
+.cf-global {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fonu-space-4);
+  padding: 12px var(--fonu-space-5);
+  margin-bottom: var(--fonu-space-4);
+  border: 1px solid var(--fonu-border);
+  border-radius: var(--fonu-radius-sm);
+  background: var(--fonu-surface);
+}
+.cf-global--off { border-color: var(--fonu-warning); background: var(--fonu-bg); }
+.cf-global__text { display: grid; gap: 4px; font-size: 13px; }
+.cf-global__text span { color: var(--fonu-text-secondary); }
 .cf-alert { margin-bottom: var(--fonu-space-4); }
 .cf-empty { padding: 24px 0; color: var(--fonu-text-muted); }
 .cf-row {

web/src/views/ExampleView.vue

@@ -8,7 +8,7 @@
     </template>
   </PageHeader>
 
-  <n-alert type="success" :bordered="false" class="example-alert" title="v1.7.0 示例页面验证标识已生效">
+  <n-alert type="success" :bordered="false" class="example-alert" title="v1.8.0 示例页面验证标识已生效">
     当前页面由 v{{ version }} 提供，验证标识为 <span class="mono">{{ verificationMarker }}</span>。
     如果你是在升级后首次看到这行内容，说明前端构建、镜像重建和服务重启均已成功。
   </n-alert>
@@ -19,7 +19,7 @@
       <strong class="example-proof__value">{{ verificationRound }}</strong>
     </div>
     <div class="example-proof__hint">
-      看到这个新区块，说明前端资源已经从旧版本切换到 v1.7.0。
+      看到这个新区块，说明前端资源已经从旧版本切换到 v1.8.0。
     </div>
   </div>
 
@@ -33,16 +33,16 @@
     <StatCard label="本次验证标识" :value="verificationMarker" sub="用于区分升级前后的前端资源" tone="blue" value-small>
       <template #icon><n-icon :component="FlashOutline" /></template>
     </StatCard>
-    <StatCard label="页面状态" value="已更新" sub="v1.7.0 前端资源已加载" tone="teal">
+    <StatCard label="页面状态" value="已更新" sub="v1.8.0 前端资源已加载" tone="teal">
       <template #icon><n-icon :component="CheckmarkCircleOutline" /></template>
     </StatCard>
   </div>
 
   <FonuCard title="本次示例页变化" subtitle="用于确认升级后的页面内容确实发生变化">
     <ul class="example-changes">
-      <li>页面版本提示更新为 v1.7.0。</li>
-      <li>「本次升级验证」区块和页面状态同步更新为 v1.7.0。</li>
-      <li>验证标识更新为 <span class="mono">v1.7.0-example-page</span>。</li>
+      <li>页面版本提示更新为 v1.8.0。</li>
+      <li>「本次升级验证」区块和页面状态同步更新为 v1.8.0。</li>
+      <li>验证标识更新为 <span class="mono">v1.8.0-example-page</span>。</li>
     </ul>
   </FonuCard>
 
@@ -87,8 +87,8 @@ const message = useMessage()
 const version = ref(__APP_VERSION__)
 const checkedAt = ref('')
 const refreshing = ref(false)
-const verificationRound = 'v1.7.0'
-const verificationMarker = 'v1.7.0-example-page'
+const verificationRound = 'v1.8.0'
+const verificationMarker = 'v1.8.0-example-page'
 
 async function refreshVersion() {
   refreshing.value = true