@hjd-hitsz/claudex-web 4.1.5 → 4.2.0

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.
Files changed (80) hide show
  1. package/.env.example +2 -0
  2. package/CHANGELOG.md +31 -0
  3. package/README.md +13 -1
  4. package/bin/auth.mjs +86 -0
  5. package/bin/claudex-web.mjs +20 -0
  6. package/bin/p2p.mjs +134 -0
  7. package/build-info.json +4 -4
  8. package/client/dist/app.js +104 -104
  9. package/client/dist/code-highlight-style.js +1 -1
  10. package/client/dist/document-editor.js +54 -54
  11. package/client/dist/file-panel.js +5 -5
  12. package/client/dist/notification-worker.js +2 -1
  13. package/client/dist/p2p-sw.js +162 -0
  14. package/client/dist/style.css +1 -1
  15. package/client/dist/terminal-panel.js +11 -11
  16. package/docs/architecture/backends.md +8 -1
  17. package/docs/architecture/behavior.md +159 -53
  18. package/docs/architecture.md +36 -339
  19. package/docs/background-tasks.md +30 -26
  20. package/docs/deployment.md +47 -6
  21. package/docs/development.md +107 -151
  22. package/docs/images/desktop-dark.png +0 -0
  23. package/docs/images/desktop-light.png +0 -0
  24. package/docs/images/mobile-sidebar.png +0 -0
  25. package/docs/images/mobile.png +0 -0
  26. package/docs/releases/v4.2.0.md +13 -0
  27. package/docs/versioning.md +13 -3
  28. package/package.json +9 -2
  29. package/packages/background-terminal/LICENSE +674 -0
  30. package/packages/background-terminal/README.md +17 -0
  31. package/packages/background-terminal/background-jobs.mjs +457 -0
  32. package/packages/background-terminal/background-mcp.mjs +79 -0
  33. package/packages/background-terminal/background-protocol.mjs +80 -0
  34. package/packages/background-terminal/cli.mjs +14 -0
  35. package/packages/background-terminal/client.mjs +61 -0
  36. package/packages/background-terminal/codex.mjs +88 -0
  37. package/packages/background-terminal/delivery.mjs +192 -0
  38. package/packages/background-terminal/log.mjs +25 -0
  39. package/packages/background-terminal/native-watches.mjs +160 -0
  40. package/packages/background-terminal/package.json +15 -0
  41. package/packages/background-terminal/service.mjs +126 -0
  42. package/packages/translation-engine/package.json +1 -1
  43. package/server/src/application.mjs +82 -10
  44. package/server/src/auth-http.mjs +187 -0
  45. package/server/src/auth-login.mjs +144 -0
  46. package/server/src/auth-totp.mjs +233 -0
  47. package/server/src/auth.mjs +169 -220
  48. package/server/src/backends/claude/background-tasks.mjs +88 -35
  49. package/server/src/backends/claude/messages.mjs +1 -1
  50. package/server/src/backends/claude/worker-client.mjs +47 -35
  51. package/server/src/backends/claude/worker-lines.mjs +17 -0
  52. package/server/src/backends/claude/worker-server.mjs +49 -69
  53. package/server/src/backends/codex/adapter.mjs +46 -5
  54. package/server/src/backends/codex/background-service.mjs +85 -0
  55. package/server/src/backends/codex/background-task-views.mjs +87 -0
  56. package/server/src/backends/codex/background-terminals.mjs +91 -0
  57. package/server/src/backends/codex/events.mjs +11 -0
  58. package/server/src/backends/codex/methods.mjs +1 -0
  59. package/server/src/backends/codex/native-background-handoff.mjs +72 -0
  60. package/server/src/backends/codex/requests.mjs +51 -38
  61. package/server/src/backends/codex/subscriptions.mjs +34 -4
  62. package/server/src/backends/configuration.mjs +8 -0
  63. package/server/src/backends/manager.mjs +34 -32
  64. package/server/src/backends/storage.mjs +3 -14
  65. package/server/src/config.mjs +13 -0
  66. package/server/src/http/business.mjs +21 -0
  67. package/server/src/http/router.mjs +12 -25
  68. package/server/src/p2p/http.mjs +136 -0
  69. package/server/src/p2p/peers.mjs +132 -0
  70. package/server/src/p2p/service.mjs +229 -0
  71. package/server/src/p2p/storage.mjs +45 -0
  72. package/server/src/p2p/tunnel.mjs +95 -0
  73. package/server/src/p2p-http.mjs +149 -0
  74. package/server/src/p2p-peer.mjs +135 -0
  75. package/server/src/private-file.mjs +14 -0
  76. package/server/src/summary-translation.mjs +1 -1
  77. package/server/src/thread-folders.mjs +3 -13
  78. package/server/src/translation-service.mjs +3 -8
  79. package/shared/codex-preferences.mjs +9 -0
  80. package/shared/p2p-wire.mjs +157 -0
@@ -28,8 +28,8 @@ curl --cacert "${CLAUDEX_WEB_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/claud
28
28
  从[目标版本 Release](https://github.com/hjd-hitsz/claudex-web/releases) 下载 `.tgz` 和同名 `.sha256` 文件,将两者放在同一目录,然后执行以下命令。
29
29
 
30
30
  ```bash
31
- sha256sum -c claudex-web-4.1.5.tgz.sha256
32
- npm install -g ./claudex-web-4.1.5.tgz
31
+ sha256sum -c claudex-web-4.2.0.tgz.sha256
32
+ npm install -g ./claudex-web-4.2.0.tgz
33
33
  claudex-web service install
34
34
  ```
35
35
 
@@ -53,6 +53,22 @@ sudo apt-get install pamtester openssl
53
53
 
54
54
  登录状态默认保留 30 天,`AUTH_SESSION_DAYS` 可设为 1~90 天。刷新网页、重新打开浏览器或重启服务后,有效登录会自动恢复。退出会让同一浏览器的所有标签页返回登录页面,其他设备继续保持登录。到期或清除浏览器 Cookie 后需要重新登录。未发送草稿保留在原浏览器,已经提交的任务继续运行。
55
55
 
56
+ ### 双重验证
57
+
58
+ 从其他设备访问、使用 P2P 或经反向代理登录时,默认在系统密码通过后验证六位动态码。在部署电脑上直接用浏览器打开本机 HTTPS 端口,使用回环地址或该电脑的网卡 IP 时,可以凭系统密码登录。服务通过实际连接地址识别本机直连。本机签发的会话只适用于本机直连,设置页会显示验证器是否已绑定。
59
+
60
+ 多人连接同一实例时,每人可以绑定自己的认证应用。所有人使用运行 Claudex Web 的系统账号和密码,第二步用各自的验证器名称和动态码登录,共用同一工作区及其权限。
61
+
62
+ 1. 在运行网页服务的电脑上,以运行服务的同一系统用户执行 `claudex-web auth setup "李雷 手机"`,为每位使用者选择不同的名称。源码运行时,在仓库根目录执行 `npm run auth -- setup "李雷 手机"`。服务使用自定义 `CLAUDEX_WEB_CONFIG_DIR` 时,命令也指向同一个目录。
63
+ 2. 由该使用者用支持 TOTP 的认证应用扫描自己的二维码。二维码包含此验证器的私密密钥。
64
+ 3. 从其他设备访问网页或打开 P2P 授权链接,填写绑定时的名称和当前六位动态码。首次验证通过后即可登录并完成绑定。在「设置 → 连接与登录 → 账号与双重验证」可查看双重验证状态。
65
+
66
+ 省略 `setup` 的名称会绑定 `default` 验证器,这个验证器登录时可留空名称。旧版的单个验证器自动迁移为 `default`,原密钥和有效会话继续可用。缺少认证凭据的更早期网页会话须重新登录。
67
+
68
+ 用 `claudex-web auth list` 查看名称和验证状态,用 `claudex-web auth revoke "李雷 手机"` 撤销指定验证器及通过它登录的会话。更换设备时可为同一名称重新绑定。撤销最后一个验证器后,远程登录仍需先完成新的绑定。源码运行时用 `npm run auth --` 加相同子命令。
69
+
70
+ 运行 `claudex-web auth disable` 并输入 `yes` 可关闭双重验证,清除全部绑定及关联会话,之后可用系统密码登录。再次运行绑定命令会启用双重验证,并撤销关闭期间为非本机入口签发的系统密码会话。
71
+
56
72
  ### 证书配置
57
73
 
58
74
  未指定证书时,首次启动生成一年有效的本站证书,保存在 `CLAUDEX_WEB_CONFIG_DIR/tls`(默认 `~/.config/claudex-web/tls`)。证书包含 localhost、当前主机名及生成时的本机 IP,私钥仅服务用户可读。首次访问前,在服务电脑查看指纹,并与浏览器显示的证书核对,再按设备的证书管理方式安装该证书:
@@ -61,7 +77,7 @@ sudo apt-get install pamtester openssl
61
77
  openssl x509 -in "${CLAUDEX_WEB_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/claudex-web}/tls/certificate.pem" -noout -fingerprint -sha256
62
78
  ```
63
79
 
64
- 登录页和“设置 → 网页登录”中的“浏览器证书安装”提供证书下载与 Ubuntu、Windows、macOS、iPhone/iPad、Android 安装步骤。先向管理员核对证书,再下载并安装到用于访问的设备上。安装后重新打开浏览器,确认地址栏的证书警告消失,再输入登录密码。
80
+ 登录页和“设置 → 连接与登录”中的“浏览器证书安装”提供证书下载与 Ubuntu、Windows、macOS、iPhone/iPad、Android 安装步骤。先向管理员核对证书,再下载并安装到用于访问的设备上。安装后重新打开浏览器,确认地址栏的证书警告消失,再输入登录密码。
65
81
 
66
82
  Ubuntu 上,在文件管理器中打开证书下载目录,右键选择“在终端打开”。将下载的 DER 格式证书转换为 PEM 格式并安装到系统信任库,按提示输入本机管理员密码:
67
83
 
@@ -85,12 +101,14 @@ AUTH_SESSION_DAYS=30
85
101
 
86
102
  两项证书路径须同时设置,并允许服务用户读取;私钥权限应设为 600。域名、IP 或证书有效期变化时更新证书并在空闲时重启网页服务。需要重新生成自动证书时,在服务停止后将整个 `tls` 目录移至备份位置,再启动服务;客户端需重新核对和信任新证书。
87
103
 
88
- 网页端口只接受 HTTPS。旧的 HTTP 书签应改为 HTTPS;切换地址前,请先保存旧页面中的未发送草稿;新地址会单独保存浏览器偏好。使用域名反向代理时,浏览器到代理及代理到网页服务两段都使用 TLS,代理应验证上游证书,并保留原始 Host、Origin 和 WebSocket 升级头。Codex 后端的 `ws://` 仅限本机回环地址,跨主机后端必须使用 `wss://`。
104
+ 网页端口只接受 HTTPS。旧的 HTTP 书签应改为 HTTPS;切换地址前,请先保存旧页面中的未发送草稿;新地址会单独保存浏览器偏好。使用反向代理时,浏览器到代理及代理到网页服务两段都使用 TLS,代理应验证上游证书,保留访问端的原始 Host、Origin 和 WebSocket 升级头,并使用 `Forwarded` 或 `X-Forwarded-For` 标记转发。Codex 后端的 `ws://` 仅限本机回环地址,跨主机后端必须使用 `wss://`。
89
105
 
90
106
  ### 登录故障
91
107
 
92
108
  用户名或密码错误、账户锁定或到期时,请确认用户名、密码和账户状态。提示“登录暂不可用”时,由管理员检查 `pamtester` 是否安装及服务日志。非标准安装路径可通过 `AUTH_PAMTESTER=/absolute/path/to/pamtester` 指定。尝试次数过多时,请按页面提示稍后重试。
93
109
 
110
+ 动态码连续验证失败时,请确认设备和服务主机使用自动校时,再等验证器显示一组新数字后重试。页面提示本次验证结束时,重新输入系统密码进入验证页面。
111
+
94
112
  ## 命令与前台运行
95
113
 
96
114
  - `claudex-web` / `claudex-web start`:前台运行网页服务,连接已启用的 Codex 和 Claude Code。
@@ -104,6 +122,25 @@ AUTH_SESSION_DAYS=30
104
122
 
105
123
  前台运行时,在两个终端分别执行 `claudex-web backend` 和 `claudex-web`,并保持终端打开。已有可连接的后端时,直接运行 `claudex-web`。
106
124
 
125
+ ## P2P 远程访问
126
+
127
+ P2P 默认关闭。通过局域网登录后,在“设置 → 连接与登录”开启「P2P 远程访问」。公网入口就绪后,可生成、复制和删除长期链接。首次打开完整链接时,浏览器会建立 WebRTC 直连,再按[双重验证](#双重验证)的同一流程登录,即可访问聊天、文件和终端。会话有效期由 `AUTH_SESSION_DAYS` 设置。在同一浏览器里刷新、断线重连或重新打开同一条完整链接时,有效会话会自动恢复。退出、会话过期、清除站点数据或换用其他浏览器后需要重新登录。为每台设备单独生成链接,便于按设备撤销连接权限。
128
+
129
+ 在运行网页服务的电脑上,也可以通过命令行管理。命令使用网页服务的固定 HTTPS 端口,监听地址需包含本机回环地址,默认配置已满足。`create` 在隧道连接过程中最多等待 90 秒,成功后输出链接。
130
+
131
+ ```bash
132
+ claudex-web p2p enable
133
+ claudex-web p2p status
134
+ claudex-web p2p create "我的手机"
135
+ claudex-web p2p list
136
+ claudex-web p2p revoke 链接ID
137
+ claudex-web p2p disable
138
+ ```
139
+
140
+ 删除单个链接会关闭关联连接并撤销关联登录会话。关闭 P2P 会立即断开所有远程连接,保留已授权的链接供重新开启后使用。授权和隧道身份保存在网页配置目录下的 `p2p/`,随服务重启保留。请按凭据保护配置目录及备份。
141
+
142
+ 开通后,运行服务的电脑使用 OpenTunnel 提供公网 HTTPS 页面与信令,并通过 STUN 发现 WebRTC 候选地址。业务数据经 WebRTC 直连。有些网络会阻止直连,遇到这种情况可换网络并重试。若使用自托管 OpenTunnel,把 `OPENTUNNEL_API` 配置为相应的 HTTPS API 地址,再启用远程访问。保持相同的服务端与隧道身份以继续使用已发出的链接。
143
+
107
144
  ## Claude Code 与模型配置
108
145
 
109
146
  在设置的“模型与服务配置”中,点击 Codex 或 Claude Code 标题前的复选框即可启用或停用。程序自动检测当前服务账户的 CLI 安装,显示安装状态、当前 CLI 版本和 npm 官方包的最新版本;打开设置时自动检测,设置保持打开时每五分钟刷新,也可点击“重新检测”。
@@ -207,7 +244,7 @@ claudex-web service restart-when-idle
207
244
 
208
245
  日志显示实际等待的任务与上下文整理数量;执行重启后继续检查 `/healthz`,连接就绪时报告实际运行版本,重启或健康检查失败时保留失败状态。
209
246
 
210
- 升级后刷新网页,在“设置 → 关于”核对产品版本。`claudex-web version --json` 查看当前磁盘安装包,`/healthz` 中的 `version` 查看实际运行的服务,便于确认重启是否生效。
247
+ 升级后刷新网页,在“设置 → 更新与重启”核对产品版本。`claudex-web version --json` 查看当前磁盘安装包,`/healthz` 中的 `version` 查看实际运行的服务,便于确认重启是否生效。
211
248
 
212
249
  需要回退程序时,使用目标旧版本 Release 的 `.tgz` 安装地址重新安装,执行 `claudex-web service install`,再等待空闲后重启。用户配置继续保留;涉及配置或数据迁移的版本,先查看对应发布说明。
213
250
 
@@ -215,7 +252,7 @@ claudex-web service restart-when-idle
215
252
 
216
253
  ## 数据保存与迁移
217
254
 
218
- - Codex 和 Claude Code 的原生对话、配置及登录凭据继续由各自 CLI 管理。网页对话索引和供应商设置保存在 `CLAUDEX_WEB_CONFIG_DIR`;迁移网页时保留该目录,并将后端连接指向本机 CLI 的实际配置目录。网页登录与模型服务认证分别管理,系统密码仅用于登录验证,不会保存。
255
+ - Codex 和 Claude Code 的原生对话、配置及登录凭据继续由各自 CLI 管理。网页对话索引和供应商设置保存在 `CLAUDEX_WEB_CONFIG_DIR`;迁移网页时保留该目录,并将后端连接指向本机 CLI 的实际配置目录。系统密码仅用于登录验证。双重验证密钥位于网页配置目录下的私有文件 `auth/totp.sqlite`,请按登录凭据保护该目录和备份。
219
256
  - 草稿、置顶、固定文件夹、项目快捷列表和主题保存在当前浏览器中。固定文件夹在全部对话归档后仍会在刷新或重新打开网页时显示;手动添加的项目自动固定,取消固定后在下次加载时按未归档对话重新确定是否显示。使用同一浏览器及站点地址可恢复固定记录,清除站点数据会清除这些记录。
220
257
  - Codex 每个项目上次选择的模型和思考强度保存在服务所在电脑的 `CLAUDEX_WEB_CONFIG_DIR/project-models.json`。Claude Code 项目选择保存在 `CLAUDEX_WEB_CONFIG_DIR/backends/claude/project-models.json`,迁移服务时分别保留。同项目新建沿用当前选择,跨项目及重新打开网页时恢复目标项目设置,清空浏览器数据后可再次从服务端读取。保存失败时会提示重试。切换模型时保留当前思考强度,目标模型缺少该档位时采用最近的可用档位,距离相同时选较低档。
221
258
  - “未分类”对话的文件保存在 `CLAUDEX_WEB_CONFIG_DIR/workspaces/chat-XXXXXX`,首次发送时分配。迁移电脑时随 Claudex Web 配置目录一起保留。
@@ -293,3 +330,7 @@ Claude Code 的网络代理使用服务器可访问的代理地址和端口,
293
330
  通过 systemd 用户服务运行时,维护任务由独立用户单元执行;通过 `claudex-web start`、`npm start` 或 Node.js 直接启动时,由独立维护进程完成更新,并按原 Node.js、启动参数、工作目录和环境重新启动网页。原网页退出后,维护和新网页进程继续运行,日志保存在网页配置目录的 `maintenance/worker.log` 和 `maintenance/web.log`。后端 CLI 正在安装或更新时,网页更新与重启会提示等待当前任务结束。
294
331
 
295
332
  “重启服务”随时可用于重新启动整个网页服务进程,执行期间连接短暂中断,网页自动重连。网页交互终端会结束,请先保存文件编辑。原生后端由其独立服务管理。更新完成后保存编辑并手动刷新网页加载新版界面。维护进度保存在网页配置目录的 `maintenance/status.json`,执行日志可通过 `journalctl --user -u claudex-web-maintenance` 查询。
333
+
334
+ ## Codex 后台终端扩展
335
+
336
+ 在「设置 → 其他设置」勾选「为Codex开启后台终端功能」即可启动同机任务服务。已有独立服务可用 `CLAUDEX_BACKGROUND_TASKS_DIR` 指定其状态目录。配置、停止和日志读取见[后台终端说明](background-tasks.md)。