快速开始

本指南从空目录开始，带你完成独立开发包的下载、在线安装和首次启动。已有应用更新核心时使用升级指南。

1. 准备环境

• 当前终端位于一个空目录，以下称为 workspace。
• Git、GitHub CLI（gh）、Node 24+、pnpm 12.4.1、Go 1.25+、Docker Compose 已安装，Docker 已启动。Go toolchain 使用 1.26.5。无需安装 Python 或 Make；Windows 使用 WSL；命令适用于 Bash / Zsh。
• GitHub 账号具有私有仓库 igwen6w/modu 和 npm 包 @igwen6w/modu-web 的读取权限。
• 本文使用已私有发布的 0.13.0，无需克隆核心仓库。版本与发布范围见版本与文档基线。

当前下载入口是 modu-0.13.0-developer.tar.gz：包含独立应用骨架、安装工具和随附核心产物。下列步骤使用线上 Go/npm 私有包安装；只含骨架、不带核心产物的在线模板包尚未发布。

2. 登录 GitHub

执行位置：workspace/。

gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git --hostname github.com

按终端提示在浏览器完成登录。已有登录可跳过第一条；第二条配置 Git HTTPS 凭据助手，供 Go 私有包下载使用。

3. 下载开发包

执行位置：workspace/。先执行 MODU_VERSION='0.13.0'，后续下载、解压和安装命令使用这个配套版本。

gh release download "v${MODU_VERSION}" --repo igwen6w/modu --dir download
cd download

该命令下载 Release 的配套资产，包含开发包和校验清单。不要下载或使用 GitHub 自动生成的 Source code 附件。

4. 校验并解压应用

执行位置：workspace/download/。

macOS 执行：

shasum -a 256 -c SHA256SUMS

Linux / WSL 执行：

sha256sum -c SHA256SUMS

确认全部显示 OK 后，执行：

tar -xzf "modu-${MODU_VERSION}-developer.tar.gz" -C ..
cd ..
mv "modu-${MODU_VERSION}" my-app
cd my-app
cp server/.env.example server/.env

当前目录为 workspace/my-app/。my-app 可替换为自己的项目名称，目标目录应不存在。

workspace/
├── download/          # 下载包和校验文件
└── my-app/            # 你的业务应用
    ├── server/
    ├── web/
    ├── scripts/
    ├── packages/      # 开发包随附产物；以下在线安装不使用它们
    ├── package.json
    └── docker-compose.yml

5. 配置私有 npm 包读取凭据

1. 打开 GitHub Classic Token 创建页面。
2. 填写名称，例如 modu-development，设置有效期。
3. 勾选 read:packages，创建并复制 token。
4. 在 workspace/my-app/ 的终端执行以下命令；出现提示后粘贴 token，按回车：

pnpm core:login

token 按 GitHub Packages registry 保存到用户配置目录，文件权限为 600，不写入项目文件。安装和后续升级会自动读取；CI 可继续通过 MODU_NPM_TOKEN 环境变量注入。

6. 在线安装核心包并构建

执行位置：workspace/my-app/。

pnpm core:install --version "$MODU_VERSION" \
  --npm-registry https://npm.pkg.github.com \
  --npm-package @igwen6w/modu-web \
  --go-proxy direct

命令自动完成：

• 安装私有 Go module github.com/igwen6w/modu/server@v0.13.0。
• 安装私有 npm 包 @igwen6w/modu-web@0.13.0，应用仍以 @modu/web 导入。
• 安装第三方依赖，写入在线源配置 modu-sources.json，更新依赖锁文件。
• 检查配套版本、扩展和类型，构建前后端。

等待命令成功结束。无需执行 create:online，也无需构建核心仓库。

新检出应用仓库或清理依赖后，可执行 pnpm core:deps 按 frozen 模式恢复依赖，替代手工 pnpm install。

7. 首次初始化数据库

执行位置：workspace/my-app/。

pnpm app:setup

默认配置使用应用专用的 PostgreSQL、Redis。app:setup 启动 Compose、生成应用密钥、执行迁移，创建初始账号和初始字典等种子数据。此步骤仅用于首次准备本地开发环境。

8. 启动并登录

执行位置：workspace/my-app/。

pnpm dev:all

保持终端运行，等待前端编译完成。该命令同时启动前后端；按一次 Ctrl+C 会清理两个子进程。

项目	地址或值
页面	http://localhost:8000
登录账号	admin@gorave.local
登录密码	Admin@123
后端 API	http://127.0.0.1:3000/api/v1
PostgreSQL	127.0.0.1:55432
Redis	127.0.0.1:56379

9. 停止和再次启动

在 dev:all 终端按 Ctrl+C。需要停止数据库并保留数据时，在 workspace/my-app/ 执行：

pnpm services:stop

下次开发，在 workspace/my-app/ 执行：

pnpm dev:all

该命令会确保 Compose 服务就绪，但不会重复迁移或种子；已有数据保留，不需要再次安装核心包或输入 token。

10. 开发业务和检查构建

内容	位置
后端业务与扩展	my-app/server/app/
前端页面	my-app/web/src/pages/
前端路由	my-app/web/config/routes.ts
本地配置	my-app/server/.env

在 workspace/my-app/ 执行完整构建：

pnpm build

业务代码在 my-app/ 中维护，按创建独立应用调整应用名称和装配入口，并将此目录建立为独立私有仓库。保留依赖声明、锁文件和 modu-sources.json；不提交 .env、token、node_modules 或数据库数据。

常见问题

提示或现象	处理方式
私有 npm 包返回 401 / 403	确认使用 Classic PAT，包含 read:packages，且账号有包读取权限；重新执行 pnpm core:login 后重试安装。
Go 下载提示仓库不存在或认证失败	执行 gh auth status 检查登录账号和仓库权限，再执行 gh auth setup-git --hostname github.com。
安装中途失败	保留应用目录，修正错误后在同一目录重新执行第 6 步；不要重新解压覆盖已有应用。
Docker 连接失败	启动 Docker，再重试当前命令。
数据库端口被占用	初始化前同步修改应用 docker-compose.yml 的宿主机端口及 server/.env 中的 DB_PORT / REDIS_PORT。
提示 Node 版本不满足	在当前终端切换到 Node 24+，再重试。

更新已有应用

按 升级核心包 完成备份、核心更新、增量迁移和验证。已有项目更新核心后执行 pnpm app:upgrade 完成带数据库的升级，不能重跑 app:setup 代替升级；也不重新下载开发包覆盖业务源码，或重新初始化数据库。

尚未发布的纯在线模板

纯在线模板包尚未发布。它应只包含应用骨架、配置和安装工具，下载解压后执行在线安装；当前 0.13.0 开发包仍随附核心产物，用户无需克隆核心仓库。