dsh-mobile-ios 0.2.17 → 0.2.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -97,6 +97,8 @@ dsh plugin --profile desktop add /path/to/dsh-mobile-ios
97
97
  | banner 状态点红色 | 网关未起或端口被占——插件自动顺延 3082–3085,重启 DSH 再试 |
98
98
  | 手机「需要重新配对」 | 设备被电脑端撤销或凭证过期;手机端「重新配对」不清本地历史 |
99
99
  | 隧道地址变了 | Quick Tunnel 重启后域名会变(网关会广播 `addr_changed`),手机端用新地址重配对 |
100
+ | 提示「登录的 Cloudflare 账号不对」 | 本机 `~/.cloudflared/cert.pem` 不是持有该域名那个账号签发的:在终端执行 `cloudflared tunnel login`,浏览器里选**持有该域名**的账号授权,再回面板点「重新检测」。重装插件 / 重启宿主 / 改 NS 都无效 |
101
+ | 固定地址忽然变成另一个前缀 | 本机状态被重置或来自另一台电脑(`tunnel-credentials.mjs` 的 machine 归属校验会拒绝冒充)。点「开启远程」重新分配,或先「重置本机状态」 |
100
102
 
101
103
  ## 兼容性
102
104
 
@@ -266,6 +268,13 @@ bash spike0/run-demo.sh # 自动起服务 → 造 3 帧 → 跑客户
266
268
  | `GET /mobile/v1/tunnel` | 状态。`executable: missing` 表示主机未装 cloudflared,客户端应**隐藏**入口 |
267
269
  | `POST /mobile/v1/tunnel/start` | 启动,幂等。地址漂移时向在线会话广播 `gateway{event:"addr_changed"}` |
268
270
  | `POST /mobile/v1/tunnel/stop` | 关闭并回收子进程(网关退出时也会收,不留孤儿) |
271
+ | `POST /mobile/v1/tunnel/provision` | 开通固定地址(幂等)。写 DNS 前先做凭据预检,见 9.1 |
272
+ | `POST /mobile/v1/tunnel/recheck-dns` | 强制重探解析 + 强制刷新凭据预检(解开「解析异常」自锁死) |
273
+ | `POST /mobile/v1/tunnel/reset` | 清本机固定地址状态与 ingress(不碰 cert.pem、不删云端隧道),幂等 |
274
+ | `POST /mobile/v1/tunnel/login` | 发起 Cloudflare 浏览器授权(起 `cloudflared tunnel login`,返回授权链接),幂等 |
275
+ | `GET /mobile/v1/tunnel/login` | 授权进度:`idle/waiting/ok/error/canceled` + 链接 + 失败原因 |
276
+ | `POST /mobile/v1/tunnel/login/cancel` | 取消等待中的授权并回收子进程 |
277
+ | `POST /mobile/v1/tunnel/install-cloudflared` | 用户同意后从官方源自举安装 cloudflared 到私有目录 |
269
278
  | `GET /mobile/v1/diag/bundle` | 脱敏诊断包,含可直接粘贴的 `text` 字段 |
270
279
 
271
280
  三条硬约束:
@@ -275,6 +284,49 @@ bash spike0/run-demo.sh # 自动起服务 → 造 3 帧 → 跑客户
275
284
  `lastUrl` 跨 stop/start 保留,正是为了检测这种真实漂移。
276
285
  3. **诊断包不外发隐私**:不含设备 token、绝对路径、prompt 正文、产物内容(`test/ops.mjs` 有对应断言)。
277
286
 
287
+ ### 9.1 固定地址开通:换台电脑也必须能自证
288
+
289
+ 分发到另一台电脑后「分配不出固定地址」的根因不是网络,而是**本机凭据与状态的归属**。
290
+ 这条链路上有五条不可放松的规则(对应 `test/tunnel-credentials.mjs`):
291
+
292
+ | 规则 | 实现 | 为什么 |
293
+ |---|---|---|
294
+ | 开通前预检 cert 的可用性 | `zone-health.verifyCertAccess` | 跨账号的 cert 能列/建隧道、只有写 DNS 会失败;等 CLI 报错时用户已拿到「隧道正常」的假象 |
295
+ | 预检只在**确定**不可用时拦人 | `blocking` 状态集 | 断网/证书格式不认识 → `unknown`,不能因此判死一台本来能用的机器 |
296
+ | 失败信息保留 `code/reason` | `tunnel-error.explainTunnelFailure` | 旧实现 `split('\n')[0]` 把 `code: 10000, Authentication error` 丢掉,只剩命令回显 |
297
+ | 状态带机器归属 | `tunnel-state.machineIdentity` + `isForeignState` | 整份 `~/.dsh` 被拷到新机器时,旧地址指向旧机器;新机器绝不能冒充 |
298
+ | 没有 cert.pem 也能起隧道 | `LocalStateProvisioner` | 本地 ingress 与 tunnel 凭据都在本机,日常启动不需要 zone 凭据;端口顺延只重写本地配置 |
299
+
300
+ 诊断矩阵(`TunnelStatus.credentials.state`):`ok` / `missing`(没有 cert) / `unreadable`(解析不了,降级)
301
+ / `no-token`(旧版证书,降级) / `forbidden`(403) / `zone-missing`(这账号看不到域名) /
302
+ `zone-scoped-other`(证书授权的是**另一个域名**) / `account-mismatch`(证书账号 ≠ zone 账号) /
303
+ `stale-zone`(证书指向已被重建/删除的 zone) / `zone-moved`(域名被另一账号接管) / `unknown`(网络不可达)。
304
+
305
+ `zone-missing` 与 `zone-scoped-other` 的区别很关键:前者是账号里真没有这个域名,后者是
306
+ **登录时在浏览器里点错了域名**(zone 范围的 token 只覆盖被授权的那一把 zone)。两种情况都要
307
+ 重新授权,但后者必须在提示里点名「上次授权的是 xxx」。预检因此额外回传
308
+ `certAccountName` / `certZoneName`——否则用户在自己的账号里明明看得到目标域名,无从判断
309
+ 「我刚跑的 login 到底生效了没有」。
310
+
311
+ ### 9.2 一键重新授权(0.2.19)
312
+
313
+ 唯一正确的修法只有一个:**用持有该域名的账号重新授权**。但它需要人在浏览器里点「允许」,
314
+ 所以插件把这一步做成了一条路,而不是一句终端命令(现场教训:用户重装、重启、点重置、
315
+ 点重新检测全都无效——这些动作**都不会换掉 cert.pem**):
316
+
317
+ | 步骤 | 谁做 | 实现 |
318
+ |---|---|---|
319
+ | 点「重新授权(浏览器)」 | 用户 | 面板 `startTunnelLogin` → `POST /tunnel/login` |
320
+ | 起 `cloudflared tunnel login`、捞授权链接 | 网关 | `cloudflared-login.mjs`(进程级单例,幂等) |
321
+ | 浏览器里选账号并授权 | 用户 | 链接来自 cloudflared 输出;面板提供「复制授权链接」 |
322
+ | 轮询结果 → 强制重检 → 继续开通 | 面板 | `pollLogin` 每 1.5 秒一次,成功后 `afterLoginOk` |
323
+
324
+ 四条不变量:幂等(等待中重复点不起第二个授权)、不静默(超时/退出码非 0/退出但没生成证书
325
+ 都有可读原因,且保留 cloudflared 最后几行而不是第一行)、不留孤儿(取消或超时 kill 子进程)、
326
+ 只覆盖 `HOME`(证书一定落在本机真正使用的 `~/.cloudflared`)。
327
+
328
+ 换账号后 `ensure()` 会自动识别账号变更、重建隧道并**沿用同一个子域**(地址不变、无需重新配对)。
329
+
278
330
  ## 10. 下一步
279
331
 
280
332
  1. **X2 真宿主实跑**:desktop profile 的 `cordis.patch.yml` 打开 `host: mux` 重启,对照 diag 服务可见性。
@@ -5,7 +5,6 @@
5
5
  // 3. 宿主卸载插件时必须彻底释放 socket / 定时器,不留孤儿监听。
6
6
 
7
7
  import os from 'node:os';
8
- import fs from 'node:fs';
9
8
  import path from 'node:path';
10
9
  import { createGateway } from '../src/server.mjs';
11
10
  import { createFileLog } from '../src/file-log.mjs';
@@ -13,7 +12,7 @@ import { findCloudflared, sweepOrphanTunnels } from '../src/tunnel.mjs';
13
12
  import { createMockHost } from '../src/adapter/mock-host.mjs';
14
13
  import { createMuxHost } from '../src/adapter/mux-host.mjs';
15
14
  import { createCordisHost } from '../src/adapter/cordis-host.mjs';
16
- import { createProvisioner } from '../src/cloudflare.mjs';
15
+ import { resolveProvisioner, defaultTunnelStateFile } from '../src/provision-select.mjs';
17
16
  import { PLUGIN_VERSION } from '../src/version.mjs';
18
17
 
19
18
  export const name = 'dsh-mobile-ios';
@@ -95,62 +94,37 @@ export function apply(ctx = {}, config = {}) {
95
94
  .catch(() => { /* 清扫失败不挡启动 */ });
96
95
 
97
96
  /**
98
- * Pro 固定地址开通器。按「已经能用的证据」排序,谁先齐备用谁:
97
+ * Pro 固定地址开通器。判定统一在 resolveProvisioner(与 sidecar 同一套顺序):
99
98
  * 1. config.tunnel.provisioner(显式指定,尊重运营决定)
100
- * 2. Cloudflare API(config 或 env 里有 accountId + apiToken)
101
- * 3. 开通服务(endpoint + enrollToken,产品形态;zone 权限留在服务端)
99
+ * 2. 开通服务(endpoint + enrollToken,产品形态;zone 权限留在服务端)
100
+ * 3. Cloudflare API(config 或 env 里有 accountId + apiToken)
102
101
  * 4. 本地管理型(~/.cloudflared/cert.pem 存在,说明跑过 tunnel login)
103
- * 5. 只读状态(以前开通过,日常启动不该再要 zone 凭据)
102
+ * 5. 只读状态(以前开通过,日常启动不该再要 zone 凭据;token 或本地 ingress 两种形态)
104
103
  * 都没有就保持 Quick Tunnel——免费层行为一字不改。
104
+ *
105
+ * 两个入口共用同一个判定,是为了避免「同一台机器换个启动方式就换一种结论」:
106
+ * 那会让固定地址时有时无,用户只会觉得插件坏了。
105
107
  */
106
108
  const tunnelCfg = config.tunnel || {};
107
- const tunnelStateFile = tunnelCfg.stateFile || path.join(os.homedir(), '.dsh', 'mobile-access', 'tunnel-named.json');
108
- const baseDomain = tunnelCfg.baseDomain || process.env.DSH_TUNNEL_BASE_DOMAIN || 'matrixboard.cn';
109
+ const tunnelStateFile = tunnelCfg.stateFile || defaultTunnelStateFile();
109
110
  const cloudflareBin = resolveCloudflared(config);
110
- const common = {
111
- baseDomain,
112
- prefix: tunnelCfg.prefix || 'dsh',
113
- // 没找到就留 'auto':让发现链在真正要用的那一刻再解析一次(自动安装发生在启动之后)
114
- executable: cloudflareBin,
115
- };
116
- const explicit = tunnelCfg.provisioner ? String(tunnelCfg.provisioner) : null;
117
- const apiToken = tunnelCfg.apiToken || process.env.DSH_CF_API_TOKEN;
118
- const accountId = tunnelCfg.accountId || process.env.DSH_CF_ACCOUNT_ID;
119
- const endpoint = tunnelCfg.endpoint || process.env.DSH_TUNNEL_ENDPOINT;
120
-
121
- let provisioner = null;
122
- if (explicit === 'state') {
123
- provisioner = createProvisioner({ ...common, provisioner: 'state' }, { log, stateFile: tunnelStateFile });
124
- if (provisioner && !provisioner.configured) provisioner = null;
125
- } else if (explicit === 'local') {
126
- provisioner = createProvisioner({ ...common, provisioner: 'local' }, { log, stateFile: tunnelStateFile });
127
- if (provisioner && !provisioner.configured) provisioner = null;
128
- } else if (explicit === 'hosted' || (!explicit && endpoint)) {
129
- provisioner = createProvisioner(
130
- { ...common, provisioner: 'hosted', endpoint, enrollToken: tunnelCfg.enrollToken || process.env.DSH_TUNNEL_ENROLL_TOKEN },
131
- { log, stateFile: tunnelStateFile, hostId: 'host_cordis' },
132
- );
133
- } else {
134
- provisioner = createProvisioner(
135
- { ...common, provisioner: 'cloudflare', apiToken, accountId, zoneId: tunnelCfg.zoneId || process.env.DSH_CF_ZONE_ID },
136
- { log, stateFile: tunnelStateFile },
137
- );
138
- if (!provisioner) {
139
- const local = createProvisioner({ ...common, provisioner: 'local' }, { log, stateFile: tunnelStateFile });
140
- if (local?.configured) provisioner = local;
141
- }
142
- }
143
111
 
144
- // 没有开通凭据,但这台机器以前开通过:用只读状态继续跑固定地址。
145
- // 日常启动不该依赖 zone 级凭据——token 就在 0600 状态文件里。
146
- if (!provisioner && fs.existsSync(tunnelStateFile)) {
147
- const fromState = createProvisioner({ provisioner: 'state', baseDomain }, { log, stateFile: tunnelStateFile });
148
- if (fromState?.configured) {
149
- provisioner = fromState;
150
- log('tunnel 复用已开通的固定地址(只读状态,无 zone 凭据)');
151
- }
152
- }
153
- if (provisioner) log(`tunnel 固定地址开通器=${provisioner.kind} 域名=${provisioner.baseDomain}`);
112
+ const provisioner = resolveProvisioner({
113
+ tunnelCfg: {
114
+ ...tunnelCfg,
115
+ // 环境变量兜底:与 sidecar 一致,避免只在某个入口生效
116
+ apiToken: tunnelCfg.apiToken || process.env.DSH_CF_API_TOKEN,
117
+ accountId: tunnelCfg.accountId || process.env.DSH_CF_ACCOUNT_ID,
118
+ zoneId: tunnelCfg.zoneId || process.env.DSH_CF_ZONE_ID,
119
+ endpoint: tunnelCfg.endpoint || process.env.DSH_TUNNEL_ENDPOINT,
120
+ enrollToken: tunnelCfg.enrollToken || process.env.DSH_TUNNEL_ENROLL_TOKEN,
121
+ baseDomain: tunnelCfg.baseDomain || process.env.DSH_TUNNEL_BASE_DOMAIN || 'matrixboard.cn',
122
+ executable: cloudflareBin,
123
+ },
124
+ stateFile: tunnelStateFile,
125
+ hostId: 'host_cordis',
126
+ log,
127
+ });
154
128
 
155
129
  const booting = createGateway({
156
130
  host,
@@ -1,11 +1,10 @@
1
1
  // entries/sidecar.mjs — 独立进程入口(X1 不通过时的降级路径)
2
2
  // 与插件入口共用同一个 core:形态不同,契约一致。
3
3
 
4
- import fs from 'node:fs';
5
4
  import os from 'node:os';
6
5
  import path from 'node:path';
7
6
  import { createGateway } from '../src/server.mjs';
8
- import { createProvisioner } from '../src/cloudflare.mjs';
7
+ import { resolveProvisioner } from '../src/provision-select.mjs';
9
8
  import { createMockHost } from '../src/adapter/mock-host.mjs';
10
9
  import { createMuxHost } from '../src/adapter/mux-host.mjs';
11
10
 
@@ -33,11 +32,13 @@ if (hostKind === 'mux') {
33
32
  log(`mux probe ${probe.ok ? 'OK' : 'FAIL'} status=${probe.status} ${probe.url}`);
34
33
  }
35
34
 
36
- // 固定地址开通器(可选):有凭据就切 named 模式,没有保持 Quick Tunnel。
37
- const tunnelStateFile = args['tunnel-state'] || path.join(os.homedir(), '.dsh', 'mobile-access', 'tunnel-named.json');
38
- let provisioner = createProvisioner(
39
- {
40
- provisioner: args['tunnel-provisioner'] || (args['tunnel-endpoint'] || process.env.DSH_TUNNEL_ENDPOINT ? 'hosted' : 'cloudflare'),
35
+ // 固定地址开通器(可选):判定与插件入口共用 resolveProvisioner——
36
+ // 同一台机器换个启动方式不该得到不同结论(那会让固定地址时有时无)。
37
+ const tunnelStateFile = args['tunnel-state'] || process.env.DSH_TUNNEL_STATE_FILE
38
+ || path.join(os.homedir(), '.dsh', 'mobile-access', 'tunnel-named.json');
39
+ const provisioner = resolveProvisioner({
40
+ tunnelCfg: {
41
+ provisioner: args['tunnel-provisioner'] || undefined,
41
42
  apiToken: args['cf-token'] || process.env.DSH_CF_API_TOKEN,
42
43
  accountId: args['cf-account'] || process.env.DSH_CF_ACCOUNT_ID,
43
44
  zoneId: args['cf-zone'] || process.env.DSH_CF_ZONE_ID,
@@ -45,31 +46,11 @@ let provisioner = createProvisioner(
45
46
  prefix: args['tunnel-prefix'] || 'dsh',
46
47
  endpoint: args['tunnel-endpoint'] || process.env.DSH_TUNNEL_ENDPOINT,
47
48
  enrollToken: args['tunnel-enroll'] || process.env.DSH_TUNNEL_ENROLL_TOKEN,
48
- },
49
- {
50
- log,
51
- stateFile: tunnelStateFile,
52
- },
53
- );
54
- // 本地管理型:跑过 `cloudflared tunnel login`(~/.cloudflared/cert.pem 存在)就能开通。
55
- if (!provisioner && fs.existsSync(path.join(os.homedir(), '.cloudflared', 'cert.pem'))) {
56
- const localCfg = {
57
- provisioner: 'local',
58
- baseDomain: args['tunnel-domain'] || process.env.DSH_TUNNEL_BASE_DOMAIN || 'matrixboard.cn',
59
- prefix: args['tunnel-prefix'] || 'dsh',
60
49
  executable: args['tunnel-bin'] || 'cloudflared',
61
- };
62
- const local = createProvisioner(localCfg, { log, stateFile: tunnelStateFile });
63
- if (local?.configured) provisioner = local;
64
- }
65
- // 已开通过的机器:没有凭据也能按状态文件起固定地址(token 在 0600 文件里)。
66
- if (!provisioner && fs.existsSync(tunnelStateFile)) {
67
- const fromState = createProvisioner(
68
- { provisioner: 'state', baseDomain: args['tunnel-domain'] || process.env.DSH_TUNNEL_BASE_DOMAIN || 'matrixboard.cn' },
69
- { log, stateFile: tunnelStateFile },
70
- );
71
- if (fromState?.configured) provisioner = fromState;
72
- }
50
+ },
51
+ stateFile: tunnelStateFile,
52
+ log,
53
+ });
73
54
 
74
55
  const gw = await createGateway({
75
56
  host,