项目初始化（Quick Start）

本指南用于在本地完成 Ape‑Volo‑Admin（后端） 与 Ape‑Volo‑Web（前端） 的初始化与启动，并验证服务可用与登录成功。

📋 前置条件

在开始之前，请确认已满足以下条件（以项目 README/实际配置为准）：

• ✅ 环境准备：已安装 Node.js、.NET SDK 等
• ✅ 已克隆前后端代码到本地（建议保持前后端目录同级，便于配置与联调）
• ✅ 数据库服务可用（若使用内置/本地文件型数据库，也需具备读写权限）
• ✅ 端口未被占用（后端与前端默认端口见下文示例，实际以项目配置为准）

建议：首次启动前先通读一次后端与前端的 README，确认运行方式、端口、以及环境变量/配置文件位置。

🚀 获取代码

1. 克隆项目

# GitHub（主分支）
git clone https://github.com/xianhc/ape-volo-admin
git clone https://github.com/xianhc/ape-volo-web

网络不佳可使用 Gitee：

git clone https://gitee.com/xianhc/ape-volo-admin.git
git clone https://gitee.com/xianhc/ape-volo-web.git

---

🔧 启动后端服务（ape-volo-admin）

1. 打开项目

可使用 Rider 或 Visual Studio 2022 打开解决方案。

• 启动环境建议使用：Development
• 如项目包含多个启动入口，请选择 Web API/Host 类项目作为启动项（以解决方案结构为准）

2. 配置检查（建议）

启动前建议快速确认以下配置入口（路径/文件名以项目实际为准）：

• appsettings.json / appsettings.Development.json
  • System.MainDatabase主库 ID
  • System.LogDatabase日志库 ID
  • DataConnection.ConnectionItem：数据库连接字符串集合
• 若使用环境变量覆盖配置，请确保 IDE/启动配置中已设置
• 查看具体配置

3. 启动后端

方式 A：IDE 启动
在 IDE 中点击“运行/调试”。

方式 B：命令行启动（在后端项目目录内，按实际启动项目调整路径）

# 示例：进入包含 Program.cs 的启动项目目录后运行
dotnet restore
dotnet run

4. 首次启动会发生什么

首次启动通常会执行初始化逻辑（以项目实现为准），常见包含：

1. 默认数据库类型（Sqlite）
2. 创建/初始化日志库
3. 创建主库结构并写入种子数据
4. 创建多租户场景下的库/表初始化（如开启且使用库隔离模式）

注意：若初始化失败，优先检查数据库连接字符串、权限、以及是否存在旧版本残留数据。

5. 验证后端是否启动成功

控制台出现类似输出表示已监听端口（示例）：

Now listening on: http://[::]:8002
Application started. Press Ctrl+C to shut down.
Hosting environment: Development

然后访问健康检查接口（以文档约定为准）：

• http://localhost:8002/health/index

若返回健康状态/可访问页面，说明后端已可用。

---

🎨 启动前端应用（ape-volo-web）

1. 打开前端项目

使用 WebStorm 或 VS Code 打开前端项目根目录。

2. 安装依赖

⚠️ Node.js 版本要求

确保您的 Node.js 版本 >= 18.16.2（若 README 要求更高版本，以 README 为准）

三选一即可（推荐 pnpm）：

# npm
npm install

# yarn
yarn install

# pnpm（推荐）
pnpm install

若安装依赖失败（网络/镜像问题），可切换 npm registry 或使用更稳定的镜像源后重试。

3. 启动开发服务器

# npm
npm run dev

# yarn
yarn dev

# pnpm
pnpm dev

启动成功后会看到类似输出（示例）：

  ➜  Local:   http://localhost:8001/
  ➜  Network: http://172.18.4.80:8001/

4. 联调检查（前后端连通）

• 确认后端已启动且健康检查可访问
• 若前端请求后端出现 404/跨域/代理失败：
  • 检查前端的开发代理/后端地址配置（例如 devServer proxy / env 配置等，位置以项目实际为准）
  • 确认前端配置的后端端口与后端实际监听端口一致（示例后端 8002）

---

🗄️ 登录系统

1. 打开登录页

• http://localhost:8001/#/login

2. 使用默认管理员账号（仅用于本地开发）

• 用户名：apevolo
• 密 码：123456

安全提示：默认账号/默认密码仅建议用于本地体验与开发联调；部署到测试/生产环境前务必修改并做好权限与密钥管理。