From d99c4c08bba9791ee00dfa8659792893c8c2a5b4 Mon Sep 17 00:00:00 2001 From: fylorn <249551762+fylorn@users.noreply.github.com> Date: Fri, 25 Sep 2026 20:04:06 +0800 Subject: [PATCH] docs(core): server guide from ThinkWatch Core v0.49.1 Refresh the fallback copy of Core's docs to v0.49.1, whose server guide matches the desktop app's connection dialog and its version rule (ThinkWatch-Core#199). Merging also redeploys the site, so the live page picks up the new release right away. Co-Authored-By: Claude Opus 5.5 --- src/data/core-docs/manifest.json | 6 +-- src/data/core-docs/server.md | 82 +++++++++++++++++++++--------- src/data/core-docs/server.zh-CN.md | 34 ++++++++----- 3 files changed, 83 insertions(+), 39 deletions(-) diff --git a/src/data/core-docs/manifest.json b/src/data/core-docs/manifest.json index 384d465..cb81cf0 100644 --- a/src/data/core-docs/manifest.json +++ b/src/data/core-docs/manifest.json @@ -1,10 +1,10 @@ { "repository": "ThinkWatchProject/ThinkWatch-Core", - "ref": "v0.48.0", + "ref": "v0.49.1", "files": { "docs/config.md": "0cc9efd9cbb11ea69b3cf17e2d980376580afe6e3b38d628fe2f4be883ad18fb", "docs/config.zh-CN.md": "54a095a491f8f2ce711f6f58166e2fc95d130a2c6bd53b9236af93147a598368", - "docs/server.md": "60d35704d27e2abf0943ef9113633ab5ab8ca0bc398a79626502b18779641acc", - "docs/server.zh-CN.md": "fb2d02e20cf30132ab8a487e88000224ec9952a4bef999187f7049b0728d6c7c" + "docs/server.md": "5e1e9b901bef2b46d417aea057a1db24c78457d3c1938b8540ecb4766515b68f", + "docs/server.zh-CN.md": "1f508e7c39b8ded28653773ca4d8701e6bdc2247bcd359c3a8fd00fd1401a6ff" } } diff --git a/src/data/core-docs/server.md b/src/data/core-docs/server.md index 319ba24..2d683de 100644 --- a/src/data/core-docs/server.md +++ b/src/data/core-docs/server.md @@ -16,8 +16,12 @@ upgrading. Every field mentioned is described in the - Linux on x86_64 or aarch64, with glibc 2.35 or newer (Ubuntu 22.04, Debian 12, or later). - systemd. -- The server's core version has to match the desktop app's. The app checks - this when it connects and shows both versions if they differ. +- On the server, the core version that the desktop app includes. The app + connects only to a core that speaks the same version of the control-plane + protocol: it checks this during the handshake and, when the versions + differ, refuses the connection and shows both, the version on the server + and the version the app needs. [Upgrading](#upgrading) describes how to + switch versions. ## 1. Install @@ -25,12 +29,18 @@ upgrading. Every field mentioned is described in the curl -fsSL https://raw.githubusercontent.com/ThinkWatchProject/ThinkWatch-Core/main/scripts/install.sh | sudo sh ``` -To install a particular version, the one your desktop app expects: +This installs the latest release, which can be newer than the core version +the desktop app includes. To install a particular version, pass it to the +script: ```sh -curl -fsSL https://raw.githubusercontent.com/ThinkWatchProject/ThinkWatch-Core/main/scripts/install.sh | sudo sh -s -- --version 0.47.0 +curl -fsSL https://raw.githubusercontent.com/ThinkWatchProject/ThinkWatch-Core/main/scripts/install.sh | sudo sh -s -- --version ``` +`` is a release number such as `0.47.0`. When the server runs a +different version, the app names the version it needs, and +[`twcore upgrade --version`](#upgrading) switches the server to it. + The script: 1. downloads `twcore--unknown-linux-gnu.tar.gz` from the GitHub @@ -176,57 +186,81 @@ interfaces that listen on it, and the allowed sources. When the port is closed the second line reads `remote control: off (twcore remote enable opens it)`. -In the desktop app, open **Settings → Connections → Add remote connection** +In the desktop app, open **Settings → Connection → Add remote connection** and enter: +- **Name**: a name for the connection, such as `home-server`; - **Address**: the server's host name or IP address; - **Control port**: `listen.control.remote.port`; - **Key**: the 64 characters `twcore control-key` printed. -The app tests the connection before saving and says what is wrong if it -fails: no answer (address, port, firewall, `enabled`), connection closed -(this computer's address is probably not in `allow_from`), wrong key, or -different versions. `allow_from` for this port does not let the server -itself in automatically; commands on the server use the local channel. +**Test connection** completes the handshake and reads the server's core +version, without saving anything. **Save and switch** runs the same test +first, saves the connection only when the test succeeds, and asks for +confirmation before switching; **Save** stores the connection without +testing it. Switching to a remote connection always tests it first, and the +app stays on its current connection when the test fails. A failed test +says what is wrong: no answer (address, port, firewall, `enabled`), +connection closed (this computer's address is probably not in +`allow_from`), wrong key, or different versions (see +[Upgrading](#upgrading)). `allow_from` for this port does not let the +server itself in automatically; commands on the server use the local +channel. A source that fails the handshake five times within a minute is ignored for a minute. Removing a network from `allow_from` also closes the connections already open from it. The desktop app stores the key in its data directory, in a file readable -only by the user who runs the app, rather than in the system keychain. To -replace it, run `twcore control-key --rotate` on the server; connections +only by the user who runs the app. To replace it, run `twcore control-key --rotate` on the server; connections made with the old key are closed at once, and connected apps then have to be given the new key. -A remote connection can do everything the app does on its own computer +A remote connection can do everything the app does with its local core except three things, which the server refuses: stopping core (systemd runs it), taking the diagnostic bundle, and changing `listen.control`, -the section it came in through. Do those on the server. +the section it came in through. Do those on the server. ChatGPT accounts +are signed in with a device code while the app is connected to a remote +core, because a browser sign-in returns to the machine that runs core. ### Point clients at the server Clients use the server's gateway, `http://:8788`, with a gateway key -from `clients`. The desktop app can point the clients on its own computer at -the server (Clients page); on other machines, configure them by hand. +from `clients`. The desktop app can point the clients on the machine it +runs on at the server (Clients page); on other machines, configure them by +hand. ## Upgrading +The server has to run the core version that the desktop app includes. When +the two differ, for example after the app updates to a release that +includes a newer core, the app refuses the connection and shows both +versions. Switch the server to the version the app needs: + +```sh +sudo twcore upgrade --version --restart +``` + +With `--version`, `twcore upgrade` installs the named release even when it +is older than the installed one, so the same command moves the server +forward or back. Recent versions of the app show this command, with the +version filled in, when the versions differ. + +Without `--version`, `twcore upgrade` compares with, and installs, the +latest release, which can be newer than the version the app needs: + ```sh sudo twcore upgrade --check # compare with the latest release, change nothing sudo twcore upgrade --restart # install the latest release and restart the service -sudo twcore upgrade --version 0.48.0 --restart ``` `twcore upgrade` downloads the release for this machine, checks its SHA-256 sum, and replaces `/usr/local/bin/twcore` in one step, so a failed -download never leaves a broken binary. The configuration and the data are -not touched. Without `--restart` it prints the command to restart the -service; the running process keeps the old version until then. - -Upgrade the server and the desktop app together: the app refuses to connect -to a core of another version and shows the command above with the version -it needs. +download never leaves a broken binary. It does not touch the configuration +or the data. Without `--restart` it prints the command to restart the +service; the running process keeps the old version until then. A version +that stores request history in a different format from the previous one +starts with an empty request history; the configuration is kept. ## Uninstalling diff --git a/src/data/core-docs/server.zh-CN.md b/src/data/core-docs/server.zh-CN.md index 3b253d3..50d025e 100644 --- a/src/data/core-docs/server.zh-CN.md +++ b/src/data/core-docs/server.zh-CN.md @@ -10,7 +10,7 @@ ThinkWatch Core 可以脱离桌面运行：在 Linux 机器上由 systemd 按配 - x86_64 或 aarch64 的 Linux，glibc 2.35 或更新（Ubuntu 22.04、Debian 12 及以后）。 - systemd。 -- 服务器上的 core 版本须与桌面应用一致。应用在连接时核对版本，不一致时显示双方的版本号。 +- 服务器上运行的 core 与桌面应用内置的 core 版本相同。应用只连接控制面协议版本与自身相同的 core：它在握手时核对，版本不一致时拒绝连接，并显示双方的版本，即服务器上的版本和应用需要的版本。切换版本的方法见[升级](#升级)。 ## 1. 安装 @@ -18,12 +18,14 @@ ThinkWatch Core 可以脱离桌面运行：在 Linux 机器上由 systemd 按配 curl -fsSL https://raw.githubusercontent.com/ThinkWatchProject/ThinkWatch-Core/main/scripts/install.sh | sudo sh ``` -安装指定版本（即桌面应用要求的版本）： +这条命令安装最新版本，它可能比桌面应用内置的 core 版本更新。安装指定版本时，把版本号传给脚本： ```sh -curl -fsSL https://raw.githubusercontent.com/ThinkWatchProject/ThinkWatch-Core/main/scripts/install.sh | sudo sh -s -- --version 0.47.0 +curl -fsSL https://raw.githubusercontent.com/ThinkWatchProject/ThinkWatch-Core/main/scripts/install.sh | sudo sh -s -- --version <版本> ``` +`<版本>` 是 `0.47.0` 这样的版本号。服务器运行的版本不同时，应用会指明它需要的版本，用 [`twcore upgrade --version`](#升级) 即可把服务器切换到该版本。 + 安装脚本依次： 1. 从 GitHub Release 下载 `twcore-<架构>-unknown-linux-gnu.tar.gz`，并用 Release 中的 SHA-256 校验； @@ -135,33 +137,41 @@ allowed sources: 192.168.1.0/24 在桌面应用中打开 **设置 → 连接 → 添加远程连接**，填写： +- **名称**：连接的名称，例如 `home-server`； - **地址**：服务器的主机名或 IP 地址； - **控制端口**：`listen.control.remote.port` 的值； - **密钥**：`twcore control-key` 输出的 64 个字符。 -应用在保存前先试连，失败时说明原因：无响应（检查地址、端口、防火墙和 `enabled`）、连接被关闭（本机地址可能不在 `allow_from` 中）、密钥不正确、版本不一致。这个端口的 `allow_from` 不会自动放行服务器本机；服务器上的命令走本地通道。 +**测试连接**完成握手并读取服务器上 core 的版本，不保存任何内容。**保存并切换**先做同样的测试，通过后才保存连接，并在切换前请求确认；**保存**只保存连接，不做测试。切换到远程连接时总是先测试，测试失败则留在当前连接上。测试失败时说明原因：无响应（检查地址、端口、防火墙和 `enabled`）、连接被关闭（本机地址可能不在 `allow_from` 中）、密钥不正确、版本不一致（见[升级](#升级)）。这个端口的 `allow_from` 不会自动放行服务器本机；服务器上的命令走本地通道。 -同一来源一分钟内握手失败五次，之后一分钟不理它。从 `allow_from` 中删掉一个网段，已经从那里连着的连接也随即断开。 +同一来源一分钟内握手失败五次后，接下来一分钟内来自它的连接一律忽略。从 `allow_from` 中删掉一个网段，已经从那里连着的连接也随即断开。 -桌面应用把密钥存放在其数据目录下的一个文件中，该文件只有运行应用的用户可以读取；不使用系统钥匙串。要更换密钥，在服务器上执行 `twcore control-key --rotate`：用旧密钥建立的连接立即断开，之后已连接的应用需要填入新密钥。 +桌面应用把密钥存放在其数据目录下的一个文件中，该文件只有运行应用的用户可以读取。要更换密钥，在服务器上执行 `twcore control-key --rotate`：用旧密钥建立的连接立即断开，之后已连接的应用需要填入新密钥。 -远程连接能做应用在本机能做的一切，只有三件事服务器会拒绝：停止 core（它由 systemd 管理）、生成诊断包、修改 `listen.control`（这条连接进来的那一节）。这三件事在服务器上操作。 +远程连接能做应用对本机 core 能做的一切，只有三件事服务器会拒绝：停止 core（它由 systemd 管理）、生成诊断包、修改 `listen.control`（这条连接进来的那一节）。这三件事在服务器上操作。连接远程 core 时，ChatGPT 账号只能用设备码登录，因为浏览器登录完成后会回到运行 core 的那台机器。 ### 让客户端指向服务器 -客户端使用服务器的网关 `http://<服务器>:8788`，以及 `clients` 中的一把网关密钥。桌面应用可以把本机的客户端改为指向服务器（客户端页）；其他机器上的客户端需手动配置。 +客户端使用服务器的网关 `http://<服务器>:8788`，以及 `clients` 中的一把网关密钥。桌面应用可以把它所在机器上的客户端改为指向服务器（客户端页）；其他机器上的客户端需手动配置。 ## 升级 +服务器上须运行桌面应用内置的 core 版本。两者不一致时（例如应用更新到内置较新 core 的版本之后），应用拒绝连接并显示双方的版本。此时把服务器切换到应用需要的版本： + +```sh +sudo twcore upgrade --version <版本> --restart +``` + +带 `--version` 时，即使指定的版本比已安装的旧，`twcore upgrade` 也会安装它，因此同一条命令既能升级也能降级。较新版本的应用在版本不一致时会显示这条命令，并填好版本号。 + +不带 `--version` 时，`twcore upgrade` 与最新版本比较并安装最新版本，而最新版本可能比应用需要的版本更新： + ```sh sudo twcore upgrade --check # 与最新版本比较，不做任何改动 sudo twcore upgrade --restart # 安装最新版本并重启服务 -sudo twcore upgrade --version 0.48.0 --restart ``` -`twcore upgrade` 下载适合本机的版本，校验 SHA-256，一步替换 `/usr/local/bin/twcore`，下载失败也不会留下损坏的程序。配置和数据不受影响。不带 `--restart` 时只打印重启服务的命令；在重启之前，运行中的进程仍是旧版本。 - -服务器和桌面应用要一起升级：版本不一致时应用拒绝连接，并显示上面的命令及所需的版本。 +`twcore upgrade` 下载适合本机的版本，校验 SHA-256，一步替换 `/usr/local/bin/twcore`，下载失败也不会留下损坏的程序。它不改动配置和数据。不带 `--restart` 时只打印重启服务的命令；在重启之前，运行中的进程仍是旧版本。新版本保存请求记录的格式与原版本不同时，新版本启动后请求记录从空开始，配置保留。 ## 卸载