@hjd-hitsz/claudex-web 4.1.5 → 4.2.1
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/.env.example +2 -0
- package/CHANGELOG.md +57 -0
- package/README.md +16 -4
- package/bin/auth.mjs +86 -0
- package/bin/claudex-web.mjs +20 -0
- package/bin/p2p.mjs +134 -0
- package/build-info.json +4 -4
- package/client/dist/app.js +154 -122
- package/client/dist/code-highlight-style.js +23 -45
- package/client/dist/document-editor.js +54 -54
- package/client/dist/file-panel.js +5 -5
- package/client/dist/notification-worker.js +2 -1
- package/client/dist/p2p-sw.js +162 -0
- package/client/dist/style.css +1 -1
- package/client/dist/terminal-panel.js +11 -11
- package/docs/architecture/backends.md +11 -2
- package/docs/architecture/behavior.md +173 -59
- package/docs/architecture.md +36 -339
- package/docs/background-tasks.md +32 -26
- package/docs/deployment.md +53 -12
- package/docs/development.md +121 -149
- package/docs/images/desktop-dark.png +0 -0
- package/docs/images/desktop-light.png +0 -0
- package/docs/images/mobile-sidebar.png +0 -0
- package/docs/images/mobile.png +0 -0
- package/docs/releases/v4.2.0.md +15 -0
- package/docs/releases/v4.2.1.md +15 -0
- package/docs/versioning.md +15 -5
- package/package.json +9 -2
- package/packages/background-terminal/LICENSE +674 -0
- package/packages/background-terminal/README.md +17 -0
- package/packages/background-terminal/background-jobs.mjs +457 -0
- package/packages/background-terminal/background-mcp.mjs +79 -0
- package/packages/background-terminal/background-protocol.mjs +90 -0
- package/packages/background-terminal/cli.mjs +14 -0
- package/packages/background-terminal/client.mjs +61 -0
- package/packages/background-terminal/codex.mjs +88 -0
- package/packages/background-terminal/delivery.mjs +194 -0
- package/packages/background-terminal/log.mjs +25 -0
- package/packages/background-terminal/native-watches.mjs +160 -0
- package/packages/background-terminal/package.json +15 -0
- package/packages/background-terminal/service.mjs +126 -0
- package/packages/translation-engine/package.json +1 -1
- package/server/src/application.mjs +82 -10
- package/server/src/auth-http.mjs +187 -0
- package/server/src/auth-login.mjs +144 -0
- package/server/src/auth-totp.mjs +233 -0
- package/server/src/auth.mjs +169 -220
- package/server/src/backends/claude/background-tasks.mjs +88 -35
- package/server/src/backends/claude/messages.mjs +1 -1
- package/server/src/backends/claude/worker-client.mjs +47 -35
- package/server/src/backends/claude/worker-lines.mjs +17 -0
- package/server/src/backends/claude/worker-server.mjs +49 -69
- package/server/src/backends/codex/adapter.mjs +57 -7
- package/server/src/backends/codex/background-service.mjs +85 -0
- package/server/src/backends/codex/background-task-views.mjs +87 -0
- package/server/src/backends/codex/background-terminals.mjs +103 -0
- package/server/src/backends/codex/events.mjs +25 -1
- package/server/src/backends/codex/methods.mjs +1 -0
- package/server/src/backends/codex/native-background-handoff.mjs +72 -0
- package/server/src/backends/codex/requests.mjs +67 -38
- package/server/src/backends/codex/streaming-messages.mjs +50 -0
- package/server/src/backends/codex/subscriptions.mjs +34 -4
- package/server/src/backends/configuration.mjs +8 -0
- package/server/src/backends/manager.mjs +34 -32
- package/server/src/backends/storage.mjs +3 -14
- package/server/src/config.mjs +13 -0
- package/server/src/http/business.mjs +21 -0
- package/server/src/http/router.mjs +12 -25
- package/server/src/p2p/http.mjs +136 -0
- package/server/src/p2p/peers.mjs +132 -0
- package/server/src/p2p/service.mjs +229 -0
- package/server/src/p2p/storage.mjs +45 -0
- package/server/src/p2p/tunnel.mjs +95 -0
- package/server/src/p2p-http.mjs +149 -0
- package/server/src/p2p-peer.mjs +135 -0
- package/server/src/private-file.mjs +14 -0
- package/server/src/summary-translation.mjs +1 -1
- package/server/src/thread-folders.mjs +3 -13
- package/server/src/translation-service.mjs +3 -8
- package/shared/codex-preferences.mjs +9 -0
- package/shared/p2p-wire.mjs +157 -0
package/docs/deployment.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
npm install -g @hjd-hitsz/claudex-web
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
准备 Node.js 24.5+、npm、OpenSSL、Linux PAM、`pamtester` 和 systemd
|
|
13
|
+
准备 Node.js 24.5+、npm、OpenSSL、Linux PAM、`pamtester` 和 systemd,完成上方安装后,以运行服务的普通用户启动服务。进入网页后,在「设置 → 后端」安装并启用所需的 Codex 或 Claude Code。
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
claudex-web service install
|
|
@@ -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.
|
|
32
|
-
npm install -g ./claudex-web-4.1.
|
|
31
|
+
sha256sum -c claudex-web-4.2.1.tgz.sha256
|
|
32
|
+
npm install -g ./claudex-web-4.2.1.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
|
-
登录页和“设置 →
|
|
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
|
|
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,11 +122,30 @@ 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 安装和 npm 官方包的最新版本,页面展示检测结果。
|
|
110
147
|
|
|
111
|
-
|
|
148
|
+
未安装时点击「一键安装」,有可用更新时点击「更新至」对应版本。安装由服务器使用当前服务账户执行,在关闭设置后继续,完成后自动刷新安装和版本状态。安装或更新前需等待所属后端任务结束。安装失败会显示错误,可重试。npm 全局目录需允许当前账户写入。也可在服务电脑执行以下命令。
|
|
112
149
|
|
|
113
150
|
```bash
|
|
114
151
|
npm install -g @openai/codex
|
|
@@ -117,7 +154,7 @@ npm install -g @anthropic-ai/claude-code
|
|
|
117
154
|
|
|
118
155
|
CLI 自动从当前 Node.js 的安装目录、服务 PATH 和用户 `~/.local/bin` 查找。systemd 服务安装时记录当前 Node.js 和 PATH;更换 Node.js 安装后重新执行 `claudex-web service install` 并在空闲时重启网页服务。Claude Code 复用 `CLAUDE_CONFIG_DIR`(默认 `~/.claude`)中的认证、技能、插件和历史;Codex 沿用 `CODEX_HOME`(默认 `~/.codex`)及既有 app-server 连接。使用原生账户时,先在服务电脑以同一账户完成 CLI 登录。
|
|
119
156
|
|
|
120
|
-
|
|
157
|
+
在「设置 → 模型服务商」点击「添加供应商」,填写名称、API 地址、凭据和模型标识。可在 Claude Code 停用时配置供应商。启用 Claude Code 后,在输入框的模型菜单选择「供应商 · 模型」以新建对话。已有 Claude 对话可在任务结束后更换供应商或模型并继续。
|
|
121
158
|
|
|
122
159
|
API 地址需支持 Messages 请求及工具调用,填写服务基地址,例如 `https://model.example`,请求路径会追加 `/v1/messages`;服务有统一路径前缀时将其保留在基地址中。默认选择“Message API”使用原生请求,选择“Message API (兼容)”会将消息中的系统指令合并到顶层 `system`,用于要求这种布局的服务。模型标识和支持的思考强度、速度档位以服务实际配置为准。API Key 保存在服务器,编辑时留空保留原凭据,勾选清除会移除已保存凭据。
|
|
123
160
|
|
|
@@ -137,7 +174,7 @@ Claude Code 的对话、配置和原生账户状态继续保存在本机 CLI 原
|
|
|
137
174
|
|
|
138
175
|
## 配置
|
|
139
176
|
|
|
140
|
-
|
|
177
|
+
在「设置 → 后端」的对应卡片选择子代理模型及思考强度,强度档位随所选模型提供。Codex 子代理候选遵循「显示的模型」偏好。Claude Code 的选项按「供应商 / 模型」排列,可以为子代理选择其他供应商。保存前等待所属后端空闲。选择「原生默认」恢复原生子代理模型规则。
|
|
141
178
|
|
|
142
179
|
全局命令从 `~/.config/claudex-web/.env` 读取配置;设置 `XDG_CONFIG_HOME` 时使用其下的 `claudex-web` 目录,设置 `CLAUDEX_WEB_CONFIG_DIR` 时优先使用该目录。外部环境变量优先于 `.env`。执行 `claudex-web config init` 可创建配置并显示路径,已有配置和 npm 升级后的配置均会保留。
|
|
143
180
|
|
|
@@ -207,7 +244,7 @@ claudex-web service restart-when-idle
|
|
|
207
244
|
|
|
208
245
|
日志显示实际等待的任务与上下文整理数量;执行重启后继续检查 `/healthz`,连接就绪时报告实际运行版本,重启或健康检查失败时保留失败状态。
|
|
209
246
|
|
|
210
|
-
升级后刷新网页,在“设置 →
|
|
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 配置目录一起保留。
|
|
@@ -225,7 +262,7 @@ claudex-web service restart-when-idle
|
|
|
225
262
|
|
|
226
263
|
## 思考内容翻译
|
|
227
264
|
|
|
228
|
-
|
|
265
|
+
功能默认关闭。在「设置 → 通用」开启「思考内容翻译」后,服务器从 Microsoft 组件服务取得模型和分词组件,并通过 npm 获取 CPU 运行库,首次合计下载约 300 MB。校验后保留英译中所需文件,当前版本安装后约占 147 MiB。Linux x64(glibc 2.34+)服务器使用单线程 CPU 推理,客户端可使用任意受支持的浏览器。源码构建需要 C 编译器,预构建发行包已包含分词器。
|
|
229
266
|
|
|
230
267
|
思考消息接收完整后再翻译,流式阶段、下载及翻译等待期间继续显示原文。译文完成后可切换原文与译文,代码、公式及链接目标保持原始内容。翻译正文只在浏览器与本站服务间传输,推理在服务器本地完成。首次下载通过 HTTPS 获取组件目录及 SHA-256,组件文件沿用 Microsoft 返回的下载地址,完整校验后启用。
|
|
231
268
|
|
|
@@ -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)。
|