Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions CONTENT_SYNC.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,15 @@

## ZBoard documentation migration — 2026-09-10

ZBoard documentation is now authored in `docs/projects/zboard/`. Product introductions, installation, basic management, and plugin usage lead the navigation; contracts, design notes and historical acceptance records are separate reference sections. `zboard-document-migration.json` records each source, destination and source digest.
ZBoard documentation is now authored in `docs/projects/zboard/`. Product introductions, installation, basic management, and plugin usage lead the navigation; only current usage and integration references are published. Development plans, temporary contracts, schema snapshots and historical acceptance records are excluded. `zboard-document-migration.json` records each source, destination and source digest.

This migration uses ZBoard develop `37d1716c466ce16a1198399ac91c9de3e2c0c4f8` plus local documentation revisions. It is not a claim that every feature is in the published v0.0.1 artifact. Plugin runtime and marketplace documentation explicitly identifies the post-v0.0.1 development scope; shared-pool RAW editor additions are marked pending publication. Payments and other business extensions belong to plugins; the current payment extension interface is not implemented. Core and client evidence remains on the earlier baseline below.
This migration uses ZBoard develop `37d1716c466ce16a1198399ac91c9de3e2c0c4f8` plus local documentation revisions. It is not a claim that every feature is in the published v0.0.1 artifact. Plugin runtime and marketplace documentation explicitly identifies the post-v0.0.1 development scope; unpublished shared-pool RAW editor descriptions are excluded. Payments and other business extensions belong to plugins; the current payment extension interface is not implemented. Core and client evidence remains on the earlier baseline below.

Public ZBoard documentation must be changed here, not copied back into the ignored product `docs/` directory. Product release packaging keeps its own release-note artifact under `.github/release-notes/`.

Verification: source and production-output checks passed for 97 Markdown pages, including every sidebar entry, internal link and anchor, JSON examples and rendered HTML. The migration also removes the product release workflow dependency on its local docs directory.
Initial migration verification: source and production-output checks passed for 97 Markdown pages, including every sidebar entry, internal link and anchor, JSON examples and rendered HTML. The migration also removes the product release workflow dependency on its local docs directory.

Curation correction: removed 11 historical or superseded reference pages, rewrote rule compatibility and publication recovery as usage guides, and removed unpublished RAW editor notes. The manifest marks excluded sources rather than presenting them as live pages.

## Previous main audit — 2026-09-09

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,4 +196,4 @@ Documentation in this repository is published under the license declared by this

## ZBoard documentation ownership

ZBoard documentation is maintained in `docs/projects/zboard/`, including installation, plugin usage and technical references. The product repository retains only entry-point READMEs and build-owned release notes. Historical materials are labeled and grouped separately. See `zboard-document-migration.json` for migration provenance.
ZBoard documentation is maintained in `docs/projects/zboard/`, including installation, plugin usage and technical references. The product repository retains only entry-point READMEs and build-owned release notes. Development history is excluded from the public site. See `zboard-document-migration.json` for migration provenance.
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,4 +192,4 @@ pnpm create:project -- \

## ZBoard 文档维护

ZBoard 的安装、插件使用与技术参考统一维护在 `docs/projects/zboard/`。产品仓库保留入口说明和构建使用的发布文案,历史资料在文档站单独归档。迁移来源记录在 `zboard-document-migration.json`。
ZBoard 的安装、插件使用与技术参考统一维护在 `docs/projects/zboard/`。产品仓库保留入口说明和构建使用的发布文案,开发过程的历史资料不发布到文档站。迁移来源记录在 `zboard-document-migration.json`。
15 changes: 1 addition & 14 deletions docs/.vitepress/navigation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -171,22 +171,9 @@ const zboardSidebar: DefaultTheme.SidebarItem[] = [
page('插件开发', '/projects/zboard/plugins/development'),
page('身份接口', '/projects/zboard/plugins/identity-reference'),
page('插件治理', '/projects/zboard/plugins/governance'),
page('技术参考入口', '/projects/zboard/reference/'),
page('核心边界', '/projects/zboard/reference/core-baseline'),
page('数据模型', '/projects/zboard/reference/data-model'),
page('数据库迁移', '/projects/zboard/reference/database-migrations'),
page('配置与运行参考', '/projects/zboard/reference/'),
page('节点配置交付', '/projects/zboard/reference/node-config-delivery'),
page('内核生命周期', '/projects/zboard/reference/node-kernel-lifecycle'),
page('规则兼容性', '/projects/zboard/reference/managed-rule-compatibility'),
page('Mieru 内核契约', '/projects/zboard/reference/mieru-kernel-contract'),
]),
group('设计与历史资料', [
page('插件架构设计', '/projects/zboard/reference/plugin-system-design'),
page('插件市场设计', '/projects/zboard/reference/plugin-marketplace-design'),
page('0.0.1 发布记录', '/projects/zboard/reference/history/v0.0.1'),
page('核心 RC 验收记录', '/projects/zboard/reference/history/core-rc'),
page('历史发布清单', '/projects/zboard/reference/history/launch-checklist'),
page('历史路线图', '/projects/zboard/reference/history/roadmap'),
]),
group('English', [
page('Installation', '/projects/zboard/guides/installation-en'),
Expand Down
12 changes: 6 additions & 6 deletions docs/projects/zboard/contributing/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,9 @@ create the first administrator and finish site initialization.

The embedded SQL baseline is applied during startup. To run migrations without
starting the HTTP service, use `scripts/migrate.ps1` or `scripts/migrate.sh`.
See [database-migrations.md](/projects/zboard/reference/database-migrations) before opening an existing
development database with a newer build.
Back up an existing database before running a newer build. Review the SQL migrations
shipped with that exact build; do not apply historical baseline-squashing procedures
to a published schema.

## Manual frontend startup

Expand Down Expand Up @@ -128,8 +129,8 @@ Docker. The mixed workload defaults to 10 nodes, 1,000 subscriptions, 100,000
historical records, four concurrent readers and 100 events/second for 300 seconds.
`DURATION_SECONDS`, `EVENT_RATE` and `READERS` select other workload profiles.
The application and database share the 1 CPU / 1 GiB budget; the load generator
runs outside it. The [roadmap](/projects/zboard/reference/history/roadmap#资源和性能预算) defines latency and memory
budgets. Also verify exact accounting under replay and reordering, no OOM,
runs outside it. Set latency and memory budgets for the environment under test.
Also verify exact accounting under replay and reordering, no OOM,
explained failures and a fully drained backlog.

Real Zero revocation checks use isolated nodes and test credentials:
Expand All @@ -142,8 +143,7 @@ ZERO_ARTIFACT_DIR=/path/to/verified-linux-zero-artifact \
The artifact directory must contain `zero` and its matching `verification.json`.
Other scenarios are `exhaustion`, `group_change` and `recovery`. Verify data-plane
access after revocation and publication recovery, including existing connections;
control-plane status or a mock SSH server alone is insufficient. See also
[node publication](/projects/zboard/reference/node-config-delivery#重跑-mysql-验证) for real MySQL checks.
control-plane status or a mock SSH server alone is insufficient.

Keep raw logs, profiles, environment details, source/build hashes and per-run
reports under the ignored `.codex-local-artifacts/acceptance/` directory. A dirty
Expand Down
2 changes: 1 addition & 1 deletion docs/projects/zboard/guides/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,4 @@ English installation instructions are available in [First installation](./instal
| 排查连接和发布错误 | [故障排查](./troubleshooting) |
| 清理节点 | [节点清理](./node-cleanup) |

日常管理还包括[控制台操作](./daily-operations)、[公告与邮件](./announcements-and-email)、[DNS 与证书](./dns-and-certificates)和[系统维护](./maintenance)。实现契约与开发流程集中在[开发参考](../reference/)
日常管理还包括[控制台操作](./daily-operations)、[公告与邮件](./announcements-and-email)、[DNS 与证书](./dns-and-certificates)和[系统维护](./maintenance)。配置兼容性和发布排障见[运行参考](../reference/),插件接口见[开发指南](../plugins/development)
2 changes: 1 addition & 1 deletion docs/projects/zboard/guides/installation-en.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ Complete the site settings and create the first administrator. After initializat
5. **Activate a user subscription.** Use the basic order workflow to create an order for the plan and confirm it as an administrator.
6. **Connect a client.** In the user's account, choose the subscription format for the client and import its link. Make a connection, then check traffic usage in the console.

For a forwarding node or a shared upstream pool, continue with [network fronting](/projects/zboard/guides/network-fronting). Node installation and recovery are covered in the [node lifecycle guide](/projects/zboard/reference/node-kernel-lifecycle).
For a forwarding node or a shared upstream pool, continue with [network fronting](/projects/zboard/guides/network-fronting). Node installation and recovery are covered in the [node management guide](/projects/zboard/guides/node-management).

## Keep your data

Expand Down
2 changes: 1 addition & 1 deletion docs/projects/zboard/guides/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ docker compose -f docker-compose.release.yml --env-file .env.release logs --tail
5. **开通用户订阅。** 使用基础订单流程,创建对应套餐的订单,由管理员确认后开通订阅。
6. **连接客户端。** 在用户账户中选择对应的订阅格式,将订阅链接导入客户端;连接后回到控制台查看流量用量。

需要转发节点或共享上游代理池时,继续阅读[网络前置指南](/projects/zboard/guides/network-fronting)。节点安装和故障恢复见[节点生命周期说明](/projects/zboard/reference/node-kernel-lifecycle)。
需要转发节点或共享上游代理池时,继续阅读[网络前置指南](/projects/zboard/guides/network-fronting)。节点安装和故障恢复见[节点管理指南](/projects/zboard/guides/node-management)。

## 保存部署数据

Expand Down
21 changes: 2 additions & 19 deletions docs/projects/zboard/guides/network-fronting.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,15 +48,11 @@ A 是固定目标的原始 TCP/UDP 转发器,B 执行协议解密、用户鉴

前置服务默认“直连落地”,不需要代理池。需要代理时,在「节点资产 → A 的详情 → 共享代理池」创建池,再在服务的“A 到 B 的路径”选择“使用 A 的共享代理池”。池配置是节点内资源,只能由同一 A 上的入口引用。

::: info 代理池编辑说明的适用范围
本页关于“回填配置、完整 RAW 转表单、读取已下发 RAW”的说明来自待发布的编辑器改动,尚不属于当前正式版或已推送的开发版。现有版本支持创建共享池及转发入口引用。
:::

新建时默认提供 URLTest 自动测速池。表单支持添加和编辑 Shadowsocks、VMess、VLESS、Trojan、Hysteria2、SOCKS5 或 Mieru 代理,以及测速组、选择组和多跳链路;可以修改成员顺序和最终出口 `target`。编辑已有池会回填原有节点、分组和凭据。点击“合并表单并查看 RAW”生成当前完整 Zero JSON;粘贴完整 JSON 后,可以直接保存,也可以点击“覆盖并转为表单”。覆盖前先检查标识、成员引用和循环,失败保留原表单。未展示的高级协议参数在表单往返时保持原样;仅在主动更换协议或连接安全类型时替换对应配置。这里只接受 Zero JSON,不导入 Clash/Mihomo YAML。
新建共享池时可配置代理节点、测速组、选择组和多跳链路,并选择最终出口 `target`。配置使用 Zero JSON;保存前检查节点标识、成员引用和协议参数,具体格式见下方示例。

多条入口绑定各自的 B 协议端口,共用一份带 `pool-ID/` 前缀的代理图及测速状态,不会按入口复制 URLTest。每条入口独立生成匹配规则;选择直连的入口显式绕过池。代理池本身的内部认证不改变客户端协议在 B 完成握手和用户认证的事实。

更新池会排队发布 A,所有引用入口一起生效;删除仍被引用的池会被拒绝。删除节点资产时自动清理其入口、关联及自有代理池,不执行 SSH 或供应商清理。保存池配置经过 Zero 校验,替换配置还会检查所有已引用入口的 TCP/UDP 兼容性,失败回滚。凭据加密保存,不下发给订阅客户端,列表和保存响应也不返回配置。管理员打开编辑器时,通过独立、带审计的接口读取原始配置和凭据;响应禁止缓存。只修改名称时保留原配置,修改代理参数时携带完整配置和修订号保存。旧的入口独立代理路径保留兼容,可切换成共享池或直连。
更新池会排队发布 A,所有引用入口一起生效;删除仍被引用的池会被拒绝。删除节点资产时自动清理其入口、关联及自有代理池,不执行 SSH 或供应商清理。保存池配置经过 Zero 校验,替换配置还会检查所有已引用入口的 TCP/UDP 兼容性,失败回滚。凭据加密保存,不下发给订阅客户端,列表和保存响应也不返回配置。旧的入口独立代理路径保留兼容,可切换成共享池或直连。

完整路径示例:

Expand All @@ -76,18 +72,5 @@ A 是固定目标的原始 TCP/UDP 转发器,B 执行协议解密、用户鉴

`url_test` 在多个候选出口中选择,`relay.proxies` 则按顺序组成多跳代理链,两者含义不同。保存时由 Zero 校验结构、协议字段与引用关系;具体出口还需要支持实际使用的 TCP/UDP 路径。在“TCP 与 UDP”模式下,已知不支持 UDP 的 HTTP CONNECT、VLESS Vision 和以 SOCKS5 为最后一跳的 UDP 代理链会被明确拒绝;仅 TCP 模式允许由内核校验通过的 TCP 路径。每个共享池的出口和组标签只添加一次池前缀;旧的独立路径仍按入口隔离。

编辑时省略 `proxy_pool_id` 保留原池,提交 `0` 清除引用;直连时同时提交 `path_config: {}`。`parent_protocol_id` 是 B 的实际协议 ID,兼容旧字段 `endpoint_id`。`node_group_membership_changes` 与服务本身原子保存并创建凭据协调任务。代理池 API 是 `/api/v1/admin/node-proxy-pools`,GET 必须传 `node_id`,POST/PUT 配置字段为 `config`,保存响应不含凭据;更新携带 `revision`。管理员 `GET /api/v1/admin/node-proxy-pools/{id}/config` 返回 `pool` 元数据、原始 `config` 和带节点内标识前缀的 `compiled` 编译预览。编译预览不代表已下发。前置服务 API 继续使用管理员身份访问 `/api/v1/admin/network-entries`,更新携带当前 `revision` 防止覆盖其他管理员的修改。

前置线路保留 B 的 TLS/SNI/Reality 身份,以及 WebSocket 和 HTTP/2 的 Host;仅连接地址和端口替换为 A,避免长域名、CDN 或证书校验随入口地址发生变化。UDP 为每个客户端建立独立转发会话,避免多个用户向同一 B 协议发送数据时回包混淆。

## 回归验证

`TestSharedPoolCompilesOnceAndDirectEntryBypassesIt` 检查同池多个端口只生成一份代理图、直连规则绕过池、跨节点引用被拒绝及凭据不回显。`TestNetworkEntryRealTCPUDPForwarding` 在设置 `ZBOARD_ZERO_VALIDATE_BIN` 时运行真实 Zero,覆盖 TCP/UDP 原始转发、多跳路径、共享池,以及 B 的 VLESS 正确/错误凭据在直连和共享池路径上的认证结果;A 配置不得包含 B 的 VLESS 监听或用户 ID。

本地发布版 Zero 已通过 VLESS 认证用例。当前本地调试版在默认线程栈下运行该认证用例会栈溢出,设置 `RUST_MIN_STACK=16777216` 后通过;这项环境差异保留记录,本次未修改 Zero 内核。

### 代理池编辑与已下发 RAW(待发布)

编辑器中的“读取节点配置”调用管理员接口 `GET /api/v1/admin/node-proxy-pools/{id}/runtime`,使用已保存的节点 SSH 配置读取 `/etc/zerodenet/current.json`。响应包含来源、读取时间、节点配置 SHA-256,以及此池的代理、分组和关联转发入口/路由;不返回其他代理池和监听协议的凭据。它是节点当前发布文件的快照,不是内核内存状态查询。

此读取有 20 秒超时和 8 MiB 文件上限,并记录审计、禁止缓存。节点无法连接或文件无法读取时明确报错,不用编译预览替代真实快照,也不影响当前编辑草稿。没有启用入口引用、或尚未发布时,快照可能不包含此池,此时 `present` 为 `false`。保存后要等节点发布成功,再重新读取快照。
2 changes: 1 addition & 1 deletion docs/projects/zboard/plugins/development.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 插件开发与运维

本期提供插件市场、插件管理、离线导入、三个前后台页面范围,以及可选服务端配置进程和身份提供方登录。核心业务所有权见 [设计](/projects/zboard/reference/plugin-system-design)。
本期提供插件市场、插件管理、离线导入、三个前后台页面范围,以及可选服务端配置进程和身份提供方登录。核心业务所有权见 [插件范围与接口](/projects/zboard/plugins/governance)。

## 配置宿主

Expand Down
2 changes: 1 addition & 1 deletion docs/projects/zboard/plugins/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,6 @@ ZBoard 提供基础面板,在线支付及其他超出基础管理范围的能

当前开发版本支持扩展页面、插件自身配置、身份提供方和插件私有存储。安装时由宿主检查插件声明的能力和兼容性。

支付插件的业务接口尚未开放,也未提供内置支付渠道;“通过插件扩展”描述的是产品边界,不表示任意插件能力已经可用。可用范围以[插件契约](../reference/plugin-system-design)和所用构建为准。
支付插件的业务接口尚未开放,也未提供内置支付渠道;“通过插件扩展”描述的是产品边界,不表示任意插件能力已经可用。可用范围以[已开放接口](./governance)和所用构建为准。

插件市场是插件的查找和分发入口,需要由部署者配置市场目录与可信发布者。它不表示官方已经预置了一个包含所有扩展的公共市场。
Loading
Loading