docs(nodes): note that updating an mTLS node needs a node-admin token (#6957)

A master that reaches a node over mTLS with no bearer token is treated as
node-sync, which cannot call /server/updatePanel, so "Update panel" on such a
node fails with HTTP 403. That is intended, but the multi-node guide said the
API token is "not needed in mTLS mode" (#6953).

The guide (en/fa/ru/zh) and the node form's mTLS hint (all 14 locales) now say
that updating the node from the master still needs a token with the
node-admin scope. No logic changes.

The CI workflow's path filter does not cover internal/web/translation or docs,
so only Docs CI ran on this head; the locale-dependent tests were run locally.
This commit is contained in:
Nikan Zeyaei
2026-11-13 19:24:30 +03:30
committed by GitHub
parent 3a28d130a7
commit 21aa662629
18 changed files with 47 additions and 18 deletions
@@ -23,7 +23,7 @@ Provide the node's connection details:
| **Scheme** | `https` (default) or `http`. |
| **Address / Port**| The node panel's host and port. |
| **Base path** | The node's web base path. |
| **API token** | A Bearer token created on the node (not needed in mTLS mode). |
| **API token** | A Bearer token created on the node. Optional in mTLS mode, except for **Update panel** (needs `node-admin`). |
| **TLS verify** | `verify` (default), `skip`, `pin` (pin a cert SHA-256), or `mtls`. |
| **Inbound sync** | `all` inbounds, or `selected` by tag. |
| **Outbound tag** | Optionally reach the node **through** a named outbound (egress bridge).|
@@ -64,6 +64,14 @@ next restart.
Set the node's TLS verify mode to `mtls`. The master now presents a client
certificate instead of an API token.
<Callout type="warn">
A node reached over mTLS without a token only has the `node-sync` scope, which
cannot run **Update panel** (the node answers HTTP 403, "this API token is not
permitted to access this endpoint"). To update such a node from the master,
create an API token with the `node-admin` scope on the node and paste it into
the master's **API token** field for that node. Keep TLS verify on `mtls`.
</Callout>
</Step>
</Steps>
@@ -20,7 +20,7 @@ icon: Boxes
| **Scheme** | `https` (پیش‌فرض) یا `http`. |
| **Address / Port**| میزبان و پورت پنل نود. |
| **Base path** | مسیر پایهٔ وب نود. |
| **API token** | یک توکن Bearer که روی نود ساخته می‌شود (در حالت mTLS لازم نیست). |
| **API token** | یک توکن Bearer که روی نود ساخته می‌شود (در حالت mTLS اختیاری است، به‌جز **به‌روزرسانی پنل** که به توکن `node-admin` نیاز دارد). |
| **TLS verify** | `verify` (پیش‌فرض)، `skip`، `pin` (پین‌کردن SHA-256 گواهی) یا `mtls`. |
| **Inbound sync** | همهٔ inboundها (`all`) یا انتخاب‌شده (`selected`) بر اساس تگ. |
| **Outbound tag** | به‌اختیار از طریق یک outbound نام‌دار به نود برسید (پل خروجی). |
@@ -59,6 +59,14 @@ icon: Boxes
حالت TLS verify نود را روی `mtls` تنظیم کنید. اکنون مستر به‌جای یک توکن API یک
گواهی کلاینت ارائه می‌دهد.
<Callout type="warn">
نودی که بدون توکن و از طریق mTLS متصل شده فقط دامنهٔ `node-sync` را دارد و نمی‌تواند
**به‌روزرسانی پنل** را اجرا کند (نود پاسخ HTTP 403 با پیام
«this API token is not permitted to access this endpoint» می‌دهد). برای به‌روزرسانی
چنین نودی از مستر، روی نود یک توکن API با دامنهٔ `node-admin` بسازید و آن را در
فیلد **API token** همان نود در مستر وارد کنید. حالت TLS verify را روی `mtls` نگه دارید.
</Callout>
</Step>
</Steps>
+10 -1
View File
@@ -24,7 +24,7 @@ API этого узла. Главная панель опрашивает каж
| **Схема** | `https` (по умолчанию) или `http`. |
| **Адрес / Порт** | Хост и порт панели узла. |
| **Базовый путь** | Веб-базовый путь узла. |
| **API-токен** | Bearer-токен, созданный на узле (не нужен в режиме mTLS). |
| **API-токен** | Bearer-токен, созданный на узле (в режиме mTLS необязателен, кроме **Обновления панели** — нужен `node-admin`). |
| **Проверка TLS** | `verify` (по умолчанию), `skip`, `pin` (закрепить SHA-256 сертификата) или `mtls`. |
| **Синхронизация inbound** | `all` (все) inbound-соединения или `selected` (выбранные) по тегу. |
| **Тег исходящего**| При необходимости обращаться к узлу **через** именованное исходящее соединение (мост исходящего трафика). |
@@ -67,6 +67,15 @@ API этого узла. Главная панель опрашивает каж
Задайте на узле режим проверки TLS `mtls`. Теперь главная панель предъявляет
клиентский сертификат вместо API-токена.
<Callout type="warn">
Узел, подключённый по mTLS без токена, имеет только область `node-sync`, которая
не позволяет выполнить **Обновление панели** (узел отвечает HTTP 403,
«this API token is not permitted to access this endpoint»). Чтобы обновить такой
узел с главной панели, создайте на узле API-токен с областью `node-admin` и
вставьте его в поле **API-токен** этого узла на главной панели. Режим проверки
TLS оставьте `mtls`.
</Callout>
</Step>
</Steps>
@@ -20,7 +20,7 @@ icon: Boxes
| **Scheme** | `https`(默认)或 `http`。 |
| **Address / Port**| 节点面板的主机和端口。 |
| **Base path** | 节点的 Web 基础路径。 |
| **API token** | 在节点上创建的 Bearer 令牌(mTLS 模式下不需要)。 |
| **API token** | 在节点上创建的 Bearer 令牌(mTLS 模式下可选,但**更新面板**需要 `node-admin` 令牌)。 |
| **TLS verify** | `verify`(默认)、`skip`、`pin`(固定证书 SHA-256)或 `mtls`。 |
| **Inbound sync** | `all` 入站,或按标签 `selected`。 |
| **Outbound tag** | 可选地**通过**指定的出站到达节点(出口桥接)。 |
@@ -53,6 +53,10 @@ icon: Boxes
### 将节点切换到 mTLS
将节点的 TLS 验证模式设置为 `mtls`。现在主控将出示客户端证书而非 API 令牌。
<Callout type="warn">
通过 mTLS 连接且未提供令牌的节点只具有 `node-sync` 权限范围,无法执行**更新面板**(节点返回 HTTP 403,“this API token is not permitted to access this endpoint”)。要从主控更新此类节点,请在节点上创建具有 `node-admin` 权限范围的 API 令牌,并将其填入主控中该节点的 **API token** 字段。TLS 验证模式保持为 `mtls`。
</Callout>
</Step>
</Steps>