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
4 changes: 0 additions & 4 deletions docs/.vitepress/navigation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -175,10 +175,6 @@ const zboardSidebar: DefaultTheme.SidebarItem[] = [
page('节点配置交付', '/projects/zboard/reference/node-config-delivery'),
page('规则兼容性', '/projects/zboard/reference/managed-rule-compatibility'),
]),
group('English', [
page('Installation', '/projects/zboard/guides/installation-en'),
page('Plugin installation trust', '/projects/zboard/plugins/trust-en'),
]),
]

export const sidebar: DefaultTheme.Sidebar = {
Expand Down
119 changes: 42 additions & 77 deletions docs/projects/zboard/contributing/development.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,17 @@
# Local development
# 本地开发

This guide contains the contributor setup that does not belong in the project
overview. For product architecture and supported capabilities, start with the
repository `README.md`.
本页说明贡献者如何启动开发环境和验证改动。项目定位与功能范围见 [ZBoard 首页](../)。以下命令在产品代码仓库中执行。

## Toolchain
## 工具链 {#toolchain}

Use the versions declared by the repository instead of choosing local defaults:
使用仓库声明的版本:

- Go and the exact toolchain are declared in `backend/go.mod`;
- Node.js is pinned by the frontend and Docker build;
- pnpm is declared by `frontend/package.json#packageManager`;
- MySQL 8 is required for the current local service.
- Go 版本及工具链见 `backend/go.mod`
- Node.js 版本以前端项目及 Docker 构建配置为准。
- pnpm 版本见 `frontend/package.json` 的 `packageManager`
- 默认本地启动流程使用 MySQL 8

The environment checks can resolve the repository Go toolchain automatically:
环境检查脚本可以自动准备仓库指定的 Go 工具链:

```powershell
.\scripts\verify-env.ps1
Expand All @@ -23,35 +21,29 @@ The environment checks can resolve the repository Go toolchain automatically:
./scripts/verify-env.sh
```

## One-command startup
## 一键启动 {#one-command-startup}

The development launcher verifies dependencies, starts MySQL through Docker
Compose when necessary, creates ignored local runtime configuration,
starts the backend and optionally starts the frontend.
启动脚本会检查依赖,按需通过 Docker Compose 启动 MySQL,生成被 Git 忽略的本地运行配置,然后启动后端和可选的前端。

PowerShell:
PowerShell

```powershell
.\scripts\start-dev.ps1 -WithFrontend
```

Bash:
Bash

```bash
./scripts/start-dev.sh --with-frontend
```

Use `-SkipDependencies` or `--skip-deps` when MySQL already runs
outside the repository Compose stack. Both launchers expose additional port,
timeout and datasource options in their built-in help or parameter list.
已有独立 MySQL 服务时,使用 `-SkipDependencies` 或 `--skip-deps`。端口、超时和数据库连接选项见脚本帮助或参数说明。

The backend is available at `http://127.0.0.1:8080`; the frontend development
server defaults to `http://127.0.0.1:5173`.
后端地址为 `http://127.0.0.1:8080`,前端开发服务默认地址为 `http://127.0.0.1:5173`。

## Manual backend startup
## 手动启动后端 {#manual-backend-startup}

Manual startup requires a datasource, a JWT secret of at least 32 bytes and one
stable 32-byte credential-encryption key:
需要准备数据库连接、至少 32 字节的 JWT 密钥和固定的 32 字节凭据加密密钥:

```powershell
Set-Location backend
Expand All @@ -62,16 +54,13 @@ $env:ZBOARD_CREDENTIAL_ENCRYPTION_KEY = "<32-random-bytes-as-base64-or-hex>"
go run ./cmd/zboard -f ./etc/zboard.yaml.example
```

On an empty database the service enters installation mode. Open `/setup` to
create the first administrator and finish site initialization.
空数据库启动后进入安装模式,访问 `/setup` 创建首个管理员并完成初始化。

The embedded SQL baseline is applied during startup. To run migrations without
starting the HTTP service, use `scripts/migrate.ps1` or `scripts/migrate.sh`.
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.
服务启动时会执行内嵌 SQL 迁移。只执行迁移而不启动 HTTP 服务时,可使用 `scripts/migrate.ps1` 或 `scripts/migrate.sh`。使用新构建打开已有数据库前先备份,并检查目标构建附带的迁移文件;不要修改已发布的迁移历史。

## Manual frontend startup
## 手动启动前端 {#manual-frontend-startup}

PowerShell:

```powershell
Set-Location frontend
Expand All @@ -80,17 +69,17 @@ pnpm install --frozen-lockfile
pnpm dev
```

On Bash-compatible shells:
Bash

```bash
cd frontend
VITE_API_BASE=http://127.0.0.1:8080/api/v1 pnpm install --frozen-lockfile
pnpm install --frozen-lockfile
VITE_API_BASE=http://127.0.0.1:8080/api/v1 pnpm dev
```

## Verification
## 验证改动 {#verification}

Run checks in proportion to the changed area. A complete local verification is:
根据改动范围执行检查。完整的本地检查包括:

```powershell
Set-Location backend
Expand All @@ -102,65 +91,41 @@ pnpm test
pnpm build
```

`pnpm build` includes Vue and TypeScript type checking. API changes must also
update `backend/api/openapi.yaml` and its contract tests.
`pnpm build` 包含 Vue 和 TypeScript 类型检查。API 改动还需要同步 `backend/api/openapi.yaml` 及接口契约测试。

The repository also provides:
仓库还提供以下脚本:

- `scripts/smoke-test.*` for a running service;
- `scripts/build-all.*` for combined backend and frontend builds;
- `scripts/check-go-version.*` and `scripts/sync-go-baseline.*` for toolchain
maintenance.
- `scripts/smoke-test.*`:检查已运行的服务。
- `scripts/build-all.*`:构建后端和前端。
- `scripts/check-go-version.*`、`scripts/sync-go-baseline.*`:检查和维护 Go 工具链版本。

## Performance and stability verification
## 性能与稳定性验证 {#performance-and-stability-verification}

Run these commands from the repository root with the pinned Go toolchain
(`GO_BIN` can select its executable):
从仓库根目录执行,`GO_BIN` 可指定 Go 程序路径:

```bash
bash scripts/benchmark-accounting.sh local
bash scripts/benchmark-accounting.sh container
bash scripts/acceptance-mixed.sh
```

The accounting benchmark defaults to 100 batches per scenario and three runs;
`BENCH_TIME` and `BENCH_COUNT` override these settings. Container checks require
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. 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.
计量基准默认每个场景使用 100 个批次、运行三次,可通过 `BENCH_TIME` 和 `BENCH_COUNT` 调整。容器检查需要 Docker。混合负载默认使用 10 个节点、1,000 份订阅、100,000 条历史记录、四个并发读取方和每秒 100 个事件,持续 300 秒;通过 `DURATION_SECONDS`、`EVENT_RATE`、`READERS` 调整负载。

Real Zero revocation checks use isolated nodes and test credentials:
应用和数据库共同使用 1 CPU / 1 GiB 资源预算,负载生成器在预算之外运行。根据测试环境设定延迟和内存要求,并核对重复、乱序事件下的计量结果、失败原因和积压是否排空。

真实 Zero 撤权验证应使用隔离节点和测试凭据:

```bash
ZERO_ARTIFACT_DIR=/path/to/verified-linux-zero-artifact \
NODE_SCENARIO=expiry bash scripts/acceptance-node.sh
```

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.

Keep raw logs, profiles, environment details, source/build hashes and per-run
reports under the ignored `.codex-local-artifacts/acceptance/` directory. A dirty
build needs source hashes as well as Git HEAD. Share selected evidence through
CI/release artifacts when needed, without committing workstation journals.
制品目录需要包含 `zero` 和对应的 `verification.json`。其他场景包括 `exhaustion`、`group_change` 和 `recovery`。应验证实际代理连接、已有连接和配置恢复情况,控制接口或模拟 SSH 的结果不能替代真实连接验证。

A 500-events/second, 60-second burst and a 24-hour soak are separate acceptance
profiles. Record fault injection, restarts, queue recovery and resource trends;
restart the soak clock after changing the build or resetting the environment.
Short runs do not establish long-term stability or production capacity.
原始日志、性能记录、环境信息和源码摘要保存在被忽略的 `.codex-local-artifacts/acceptance/` 中。每秒 500 个事件的 60 秒突发与 24 小时持续运行是独立测试;更换构建或重置环境后重新计时。短时间测试不能证明长期稳定性或生产容量。

## Restricted networks
## 受限网络环境 {#restricted-networks}

`scripts/ensure-go-env.*` can install the pinned Go toolchain when it is
missing. Set `ZBOARD_GO_DOWNLOAD_BASE` to an approved mirror when direct
downloads from `go.dev` are unavailable. A preinstalled Go directory can be
selected with `ZBOARD_GOROOT_FALLBACK`.
缺少工具链时,`scripts/ensure-go-env.*` 可以安装指定 Go 版本。无法直接访问 `go.dev` 时,可将 `ZBOARD_GO_DOWNLOAD_BASE` 指向可信镜像,或通过 `ZBOARD_GOROOT_FALLBACK` 指定已安装的 Go 目录。

Do not weaken production secrets or commit generated runtime configuration to
work around a local environment problem.
不要为解决本地环境问题降低生产密钥要求,也不要提交生成的运行配置。
1 change: 0 additions & 1 deletion docs/projects/zboard/guides/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ ZBoard 的核心是基础面板。先完成安装和一条服务的配置,再
5. [开通订阅](./plans-and-orders):关联节点组、套餐与用户权益。
6. [连接客户端](./subscriptions-and-traffic):获取对应格式的订阅并查看流量。

English installation instructions are available in [First installation](./installation-en).

## 按需配置

Expand Down
109 changes: 0 additions & 109 deletions docs/projects/zboard/guides/installation-en.md

This file was deleted.

1 change: 0 additions & 1 deletion docs/projects/zboard/guides/installation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# 首次安装

[English](/projects/zboard/guides/installation-en) | [简体中文](/projects/zboard/guides/installation)

本指南使用正式发布的 Docker 镜像安装面板,并说明如何配置第一条服务。镜像已经包含后端和 Web 控制台,无需自行构建前端,也无需安装 Go 或 Node.js。

Expand Down
Loading
Loading