本地快速开始

准备工具复制标题链接

安装 Bun >=1.3.14、Git 和 Docker（macOS 可使用 Colima）。从仓库根目录执行命令。依赖默认使用 caret 范围，TypeScript 使用 tilde；提交 bun.lock，CI 使用 bun install --frozen-lockfile，通过 bun update 审查升级。

bun --version
bun install
bun tools/dev/up.ts

启动脚本建立 PostgreSQL 17（127.0.0.1:54329）与 Redis（127.0.0.1:63799），空库安装结构和基础种子，已有开发库执行待应用迁移。无需云账号。开发库 ppanel_edge 只用于手工开发，测试必须使用临时库。

配置与启动 API复制标题链接

将 apps/api/.env.example 复制为 apps/api/.env，替换其中的主密钥占位值。生成仅本地使用的随机密钥：

bun -e "console.log('v1:' + Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64'))"

不要创建 .dev.vars，否则 Wrangler 可能不读取同一个 .env。使用 MASTER_KEYS、SITE_HOSTS 和 VOLATILE_STORE，运行模式由 NODE_ENV 决定。完整名称见运行时配置。

bun run --cwd packages/db migrate status --url postgres://postgres@127.0.0.1:54329/ppanel_edge
bun run --cwd apps/api dev:worker

迁移命令读取当前进程的 DATABASE_URL 或 --url，必须直连 PostgreSQL；根目录命令不会自动读取 apps/api/.env，所以这里显式指定本机地址。Workers 本地模式从 apps/api/wrangler.jsonc 的 Hyperdrive 本地连接串访问数据库，并模拟 R2 与 Durable Objects。Bun API 可用 bun run --cwd apps/api dev 启动。

启动门户与后台复制标题链接

另开终端运行以下两个命令，各自的端口与 API 代理见其 Vite 配置：

bun run --cwd apps/portal dev
bun run --cwd apps/admin dev

在后台开发站点的 /admin/install 完成向导：设置站点、币种、业务时区、首个 root 与 TOTP。保存恢复码。初始化前 /readyz 与业务接口不就绪是预期行为；/healthz 仅检查进程存活。安装完成后先新建商品、规格与价格，再配置服务器和节点。

演示数据与检查复制标题链接

bun run --cwd apps/api seed
bun run check

演示种子创建独立临时数据库，并输出库名；它不向开发库写入，不完成安装，也不创建 root 或登录凭据。根据输出的保留/清理提示管理临时库。bun run check 的数据库测试同样使用临时库。

停止本地容器用 bun tools/dev/down.ts；清空并重建开发库是破坏性操作，仅在确认可丢弃数据时运行 bun tools/dev/reset-db.ts --yes。

继续阅读部署方式对比，选择 Workers、Bun 或 Node.js。