快速开始

假如您已经获取到 “Nexus 源码”，目标是在本机能够运行起来。还没有源码时，先阅读源码获取。

开始前准备

安装 Coding Agent

Coding Agent 是可以读取工程、修改文件、执行命令并反馈结果的 AI 助手。Nexus 已把项目规则和技能放在源码中，Agent 进入工程后即可按约定协助启动和开发。

Nexus 支持以下 Agent：Claude Code、Codex、Trae 和 GitHub Copilot。

本节以 Claude Code 为例。其他 Agent 的规则入口和技能目录见开发工具链。

1. 安装 Claude Code

macOS、Linux 或 WSL 使用官方原生安装命令：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell 使用：

irm https://claude.ai/install.ps1 | iex

macOS 也可以通过 Homebrew 安装稳定版：

brew install --cask claude-code

原生安装会自动更新。使用 Homebrew 安装时，可通过 brew upgrade claude-code 手动升级。完整安装要求以 Claude Code 官方安装文档为准。

2. 检查安装结果

claude --version

终端能够输出 Claude Code 版本号，表示命令已经安装。需要进一步诊断时执行：

claude doctor

claude doctor 只检查安装和配置，不会修改 Nexus 工程。

3. 登录 Claude Code

进入 Nexus 项目根目录并启动 Claude Code：

cd /你的路径/kesanai-nexus
claude

首次运行会引导你在浏览器中登录。Claude Code 需要支持该产品的 Claude Pro、Max、Team、Enterprise 或 Console 账号；免费 Claude.ai 账号不包含 Claude Code 使用权限。登录返回终端并看到交互界面后，即可在下一节输入 /quick-start。

截图预留Claude Code 在 Nexus 工程中启动

截取终端中的 Claude Code 欢迎界面和当前 Nexus 工程目录，不展示账号、授权信息、环境变量或密钥。

/images/getting-started/claude-code-ready.png

检测与安装环境

安装并进入 Coding Agent 后，可以继续让 Agent 检查本地运行条件。检查不满足时，由 Agent 根据当前操作系统选择合适的安装方式，安装完成后再次验证。

1. 让 Agent 准备运行环境

在 Nexus 项目根目录中，把下面的提示词完整发送给 Agent：

请为当前 Nexus 工程检查并准备本地运行环境：

1. 先识别当前操作系统、CPU 架构、Shell，以及已经安装的包管理器或 Node.js 版本管理器。
2. 确认当前目录是 Nexus 项目根目录，必须存在 package.json、app、server 和 .env.example；如果源码不完整，停止并说明缺少什么，不要自行下载其他源码。
3. 检查 Node.js 和 npm。Node.js 要求不低于 20，优先使用 22 LTS。没有安装或版本过低时，优先通过当前已有的版本管理器安装并切换；没有版本管理器时，选择适合当前系统的官方稳定安装方式。
4. 检查本地数据库运行条件：已有可用 PostgreSQL 时保留现状；没有 PostgreSQL 时检查 Docker。两者都没有时，优先建议安装 Docker，并说明安装后的磁盘占用和是否需要启动桌面应用。
5. 如果没有可用 PostgreSQL 但 Docker 已经可以运行，建议创建一个 PostgreSQL 16 开发容器。先向我说明容器名、宿主机端口、数据库名、用户名、密码和数据保存方式，等待我确认后再创建，并验证数据库可以连接。
6. 对普通且可恢复的安装直接执行。需要 sudo、管理员权限、修改 Shell 启动文件、安装桌面应用、重启电脑或创建容器时，先解释影响并等待我确认。
7. 每项安装完成后重新检查版本和运行状态。除我确认的 PostgreSQL 开发容器外，不要在这一阶段修改 .env、执行数据库迁移或启动 Nexus。
8. 最后用表格报告源码、Node.js、npm、Docker、PostgreSQL 五项状态，标明“已就绪”“已安装”或“仍需处理”，并给出下一项需要我确认的操作。

这段提示词不要求你预先知道该使用 Homebrew、Winget、APT、nvm 还是其他工具。Agent 会先检查当前电脑，优先复用已有工具，避免重复安装和破坏现有开发环境。

2. Agent 的检查标准

项目	通过标准	不满足时的处理
Nexus 源码	根目录存在 package.json、app/、server/ 和 .env.example	停止并指出缺失文件，重新从官网下载完整源码
Node.js	版本不低于 20，推荐 22 LTS	使用已有版本管理器或当前系统的稳定安装方式安装
npm	命令可用，通常随 Node.js 一起安装	修复 Node.js 安装，不单独下载来源不明的 npm
PostgreSQL	已有数据库服务可连接	保留现有服务；否则在确认配置后用 Docker 启动 PostgreSQL 16
Docker	没有本地 PostgreSQL 时可用于启动开发数据库	安装并启动 Docker；涉及桌面应用或系统权限时先确认

PostgreSQL 与 Docker 不要求同时安装：已有可用 PostgreSQL 时可以不安装 Docker；没有 PostgreSQL 时，推荐使用 Docker 启动隔离的开发数据库。

3. 确认检查结果

Agent 完成后，应给出类似下面的结果，而不是只回复“环境正常”：

| 项目       | 状态     | 检查结果             |
| ---------- | -------- | -------------------- |
| Nexus 源码 | 已就绪   | 已找到 package.json  |
| Node.js    | 已就绪   | v22.x                |
| npm        | 已就绪   | 10.x                 |
| Docker     | 已安装   | Docker Engine 可运行 |
| PostgreSQL | 已就绪   | Docker 容器端口 5433 |

如果某项仍需管理员权限或人工安装，完成 Agent 提示的操作后，把“请继续检查剩余运行条件”发给它。所有条件就绪后，再进入下一节使用 /quick-start。

Agent 启动工程（推荐）

Nexus 是 AI 原生工程。拿到源码后，推荐让 Coding Agent 使用 /quick-start 技能完成首次启动，而不必手动逐条执行安装和迁移命令。

1. 在工程根目录打开 Agent

先进入包含 package.json 的 Nexus 项目根目录，再启动 Claude Code、Codex、Trae 或 GitHub Copilot Agent。

Claude Code 可以直接输入：

/quick-start

使用其他 Agent 时，用自然语言明确指定技能（正常导入技能后）：

请使用 quick-start 技能启动当前 Nexus 工程。遇到需要我填写的配置时先说明用途，不要使用猜测值。

2. Agent 自动检查和启动

quick-start 会按当前电脑和工程的真实状态执行：

阶段	Agent 会做什么
环境检查	检查 Node.js、npm 和当前目录
依赖准备	检测 node_modules，缺失时安装依赖
配置检查	检查 .env；缺失时从 .env.example 创建
数据库检查	读取实际连接地址，确认 PostgreSQL 是否可访问
数据初始化	首次启动时执行数据库迁移
端口检查	检查默认端口 3000 是否被其他程序占用
启动验证	启动 Nexus，并输出首页、管理后台和 API 文档地址

Agent 不会编造数据库密码，也不会在端口冲突时结束其他程序。需要填写 .env 或处理冲突时，它会说明原因并等待你处理。

quick-start 不会自行启动 PostgreSQL。电脑上还没有可用数据库时，先按下方“Docker 启动开发数据库”准备数据库，然后再次输入 /quick-start。

3. 按提示完成必要配置

Agent 可能会要求你确认以下信息：

• PostgreSQL 的主机、端口、数据库名、用户名和密码；
• 本地站点地址，默认是 http://localhost:3000；
• 首次创建的管理员邮箱、姓名和密码；
• 认证与加密密钥是否仍是示例占位值。

真实密码和密钥应写入本地 .env，不要直接发送到公开 AI 对话或提交到 Git。

4. 验收启动结果

Agent 报告完成后，不要只看“启动成功”文字。用浏览器实际检查：

检查项	地址	正常结果
系统首页	http://localhost:3000/	页面正常显示
API文档	http://localhost:3000/api_docs	开启文档开关时可以访问

截图预留quick-start 技能执行完成

截取 Agent 的启动结果，保留环境检查、数据库迁移和本地访问地址；不要显示 .env、密码或密钥。

/images/getting-started/quick-start-agent.png

技能的完整边界和其他调用方式见通用技能使用。

传统运行方式

不使用 Coding Agent 时，也可以按照传统命令行流程运行 Nexus。传统方式与 AI 技能方式长期并存：两者执行的是同一套依赖安装、环境配置、数据库迁移和 Nuxt 启动流程，区别只是由 Agent 编排还是由你逐条执行。

传统方式适合以下场景：

• 希望理解每条启动命令的作用；
• 当前没有可用的 Coding Agent；
• AI 启动中途失败，需要逐步定位问题；
• 需要把启动步骤转换为脚本或团队内部规范。

方式一：Docker 启动开发数据库

这种方式只把 PostgreSQL 放进容器，Nexus 仍在本机以开发模式运行，最适合第一次体验。

1. 启动 PostgreSQL

docker run --name nexus-postgres-dev \
  -e POSTGRES_PASSWORD=nexus_dev \
  -e POSTGRES_DB=nexus \
  -p 5433:5432 \
  -d postgres:16-alpine

执行 docker ps，看到 nexus-postgres-dev 状态为 Up 即表示数据库已经启动。

截图预留开发数据库启动成功

截取终端中的 docker ps 结果，保留容器名、状态和 5433 端口映射。

/images/getting-started/postgres-running.png

2. 安装依赖并创建配置

在 Nexus 项目根目录执行：

npm install
cp .env.example .env

打开 .env，至少确认以下配置：

NUXT_DATABASE_URL=postgresql://postgres:nexus_dev@localhost:5433/nexus
NUXT_AUTH_SECRET=请替换为随机密钥
NUXT_APP_URL=http://localhost:3000
NUXT_ADMIN_EMAIL=admin@example.com
NUXT_ADMIN_PASSWORD=请替换为至少8位的密码
NUXT_ADMIN_NAME=System Admin

认证密钥可通过以下命令生成：

openssl rand -hex 32

3. 初始化数据库

npx drizzle-kit migrate

命令正常结束且没有数据库连接错误，表示表结构已经创建。

4. 启动 Nexus

npm run dev

终端出现本地访问地址且没有“启动失败”信息后，打开 http://localhost:3000。

截图预留Nexus 开发服务器启动成功

截取终端中的本地访问地址和启动完成信息，不要显示 .env 或密钥。

/images/getting-started/dev-server-running.png

5. 验证结果

检查项	地址	正常结果
前台首页	http://localhost:3000/	页面正常显示
管理后台	http://localhost:3000/admin	可使用 .env 中的管理员账号登录
用户中心	http://localhost:3000/user	登录后可以访问
API 文档	http://localhost:3000/api_docs	开启文档开关时可以访问

截图预留本地 Nexus 首页

截取首次成功打开的产品首页，用于帮助读者确认运行结果。

/images/getting-started/homepage.png

首次启动会创建管理员。如果数据库中已经存在管理员，修改 .env 中的管理员密码不会覆盖原密码。

方式二：使用已有 PostgreSQL

已经安装 PostgreSQL 时，先自行创建一个空数据库和专用账号，再把 .env 中的连接串改为真实值：

NUXT_DATABASE_URL=postgresql://用户名:密码@localhost:5432/nexus

随后从“初始化数据库”继续。不要直接使用生产数据库做本地开发。

常用命令

命令	作用
npm run dev	启动开发服务器
npm run build	构建生产版本
npm test	运行单元测试和结构测试
npm run test:watch	监听文件变化运行单元测试
npx drizzle-kit migrate	执行数据库迁移
docker logs nexus-postgres-dev	查看开发数据库日志
docker stop nexus-postgres-dev	停止开发数据库

启动失败时先检查

• ECONNREFUSED：数据库没有启动，或连接串端口错误。
• password authentication failed：数据库用户名或密码不正确。
• 端口 3000 被占用：停止占用进程，或按 Nuxt 提示使用其他端口并同步修改 NUXT_APP_URL。
• 管理员无法登录：确认这是数据库首次初始化时使用的账号；已有管理员不会被环境变量覆盖。
• 页面可打开但资产接口返回 403：NUXT_APP_URL 与浏览器实际访问地址不一致。

完整配置项见环境变量，服务器上线步骤见部署总览。