从零把四个站跑起来

面向第一次接触这个仓的人。跟着做完，本机会有一份可运行的开发环境，并且能说清 四个站分别是什么、指向哪个后端。

预计 15 分钟。需要 Node.js 20+ 和 Git。

第 1 步：装依赖（只装一次）

git clone <仓库地址> natlan-web
cd natlan-web
npm install

在仓根装，只装这一次。 这是一个单体仓：一个 package.json、一套依赖、一份 node_modules。apps/* 目录下没有 package.json，进那些目录再 npm install 是错的。

装完看一眼目录：

ui/            共享组件库，四个站都在用
apps/control   控制台
apps/peering   对等门户
apps/auth      OAuth 授权界面
apps/home      品牌首页

第 2 步：起控制台

npm run dev:control

打开 http://127.0.0.1:5173。会看到登录页。

此时前端连的是生产控制服务器 https://api.natlan.io——开发服务器只是本地的， 数据不是。如果没有生产 admin token，先跳过登录，第 5 步会讲怎么连本地后端。

登录页有两个页签：

• 管理员账号 —— 用户名 + 密码 + 人机验证；
• API Token —— 粘一个 admin token，并且可以改「控制服务器地址」。

第 3 步：起门户

另开一个终端：

npm run dev:peering

打开 http://localhost:5174。门户的登录要跳到 auth.natlan.io 再跳回来，本地闭环 需要后端配合，见 guides/point-to-another-backend.md。 不登录也能看到落地页与节点选择的骨架。

第 4 步：起授权界面

npm run dev:auth

它与另外三个站不同：没有路由，唯一入口是 /authorize，而且需要真实的 OAuth 请求参数才会渲染流程。直接打开根路径只会看到空白。

它的 dev server 把 /api 反代到 https://auth.natlan.io，与线上同源布局一致—— 所以本地开发不需要切基址，也没有 CORS。

首页没有 dev server（它是一份手写的 index.html）。要看效果就构建后用任意静态 服务器打开，或直接用浏览器打开 apps/home/index.html。

第 5 步：连本地后端

在对应 app 目录下建 .env.local：

# apps/control/.env.local
VITE_CONTROL_API=http://127.0.0.1:8000

# apps/peering/.env.local
VITE_PEERING_API=http://127.0.0.1:8000

后端侧还需要把本地来源加进 CORS 白名单。完整清单（含门户登录闭环的两项额外要求）见 guides/point-to-another-backend.md。

控制台还有一条更快的路子：不用改文件，直接在登录页的「API Token」页签里填控制服务器 地址——那个值存在 localStorage，优先于构建期缺省。

第 6 步：检查与构建

npm run check     # i18n 完整性 + 三个站的 svelte-check + 文档色板
npm run build     # 四个站全建

npm run check 里的第一项 check:i18n 值得单独认识：它守的是「组件搬进共享库后， 另一边整块回显 key」这类不会报错、类型检查也发现不了的回退。提 PR 前它必须是绿的。

单独跑某一项：

npm run check:control    # 或 check:peering / check:auth / check:i18n / check:swatches
npm run build:control    # 或 build:peering / build:auth / build:home

改了文档里的色值（设计令牌 等）之后跑一次 npm run swatches：它把每个 #rrggbb 前面的小色块图重新生成并回填。色块图是 生成物，别手改；check:swatches 会在 npm run check 里挡住忘记跑的情况。

各站的产物位置不同：

站	产物
control / peering	apps/<站>/build/
auth	apps/auth/dist/
home	apps/home/fleet.bundle.js（页面本体就是仓里的 index.html）

接下来

• 想理解为什么是单体仓、边界画在哪 → internals/architecture.md
• 想改一个共享组件并让四个站都生效 → tutorials/shared-component-walkthrough.md
• 想部署 → guides/deploy-workers.md
• 想查某个接口字段的口径 → reference/api/