Xichen Full Stack

Appearance

快速开始 ​

本文帮助新同事在本地跑通 MySQL + 后端 + Web 管理后台 最小闭环。

先看线上演示

若只想快速体验脚手架效果，可直接访问 Web 演示（admin / admin123），或从 文档首页 下载 Desktop / Mobile 安装包。

环境要求 ​

工具版本建议
Node.js>= 18（pnpm 11 建议 22+）
pnpm11.5.2（见根 package.json 的 packageManager）
Docker Desktop用于 MySQL
Java17+（若跑 Java 后端）
Python3.11+（若跑 Python 后端）
.NET SDK8+（仅 Desktop 仪器设备可选插件）

启用 pnpm：

bash
corepack enable
corepack prepare pnpm@11.5.2 --activate

1. 克隆与安装 ​

bash
git clone <repo-url> xichen-full-stack
cd xichen-full-stack
pnpm install

Electron postinstall（Desktop / 完整安装）

  • 不要用 pnpm install --ignore-scripts（除非暂时只做 Web）
  • install 可能卡在 electron postinstall（下载二进制），国内建议先设环境变量：
powershell
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
pnpm install

详见 常见问题 — Electron。

2. 启动 MySQL ​

bash
docker compose up -d

首次启动会自动执行 contracts/sql/schema.sql 建表（不含业务种子数据）。

3. 启动后端（三选一） ​

Java 单体版（默认端口 8080，上手最快） ​

bash
pnpm --filter @xichen-full-stack/server-java dev

文档：http://localhost:8080/swagger-ui.html

Java 微服务版 micro-java（对外仍 :8080，需 Nacos + RabbitMQ） ​

bash
# 先启动 Nacos、RabbitMQ，见 micro-java 文档
cd packages/micro-java && mvn install -DskipTests

pnpm --filter @xichen-micro/auth-service dev
pnpm --filter @xichen-micro/system-service dev
pnpm --filter @xichen-micro/monitor-service dev
pnpm --filter @xichen-micro/gateway dev

文档：http://localhost:8080/auth-service/swagger-ui.html
详见 micro-java 本地启动。

Python 版（默认端口 8000，可改 8080） ​

bash
cd packages/server-python
pip install -e .
pnpm dev

文档：http://localhost:8000/docs

启动顺序

后端可在 init 之前 启动；若仅有 schema、尚无 admin，日志可能出现 WARN（见 常见问题 — 启动 WARN），调用 init 后即可登录。

4. 初始化 RBAC 数据 ​

后端启动后，调用一次初始化接口（删表 → 建表 → 写入默认 admin）：

bash
# Java 后端（:8080）
curl -X POST http://localhost:8080/api/v1/system/database/init

# Python 后端（:8000）
curl -X POST http://localhost:8000/api/v1/system/database/init

默认账号：admin / admin123。详见 数据库初始化。

micro-java

与 server-java 相同，须 POST /api/v1/system/database/init；init 后重启 monitor-service。

5. 构建共享层 ​

Web / Desktop 依赖以下包，首次或变更后需 build：

bash
pnpm --filter @xichen-full-stack/types build
pnpm --filter @xichen-full-stack/auth build
pnpm --filter @xichen-full-stack/api-client build

仪器设备场景额外：pnpm --filter @xichen-full-stack/instrument build

6. 启动 Web 管理后台 ​

bash
pnpm --filter web dev

浏览器打开 http://localhost:5173

字段值
用户名admin
密码admin123

7. 启动 Desktop（可选） ​

bash
pnpm --filter desktop dev

Electron 窗口开发端口为 5174，路由使用 hash 模式。默认 不依赖 .NET / device-agent。

可选：仪器设备插件 ​

需要本地设备控制时：

bash
pnpm --filter @xichen-full-stack/instrument build
pnpm device-agent:dev

$env:DEVICE_AGENT_AUTO_START="true"
pnpm --filter desktop dev

登录后访问设备控制台：http://localhost:5174/#/instrument（Mock 设备 ID：mock-pump-1）。

详见 Desktop、device-agent。

8. 启动 Mobile（可选） ​

bash
# 复制环境变量模板
cp packages/mobile/.env.example packages/mobile/.env.development

pnpm --filter mobile dev:h5

Android App / 小程序需配置 manifest.json 的 AppID，见 Mobile。

验证清单 ​

  • [ ] GET /api/v1/health 返回正常
  • [ ] 已调用 POST /api/v1/system/database/init（或库中已有 admin 用户）
  • [ ] 登录成功并看到侧边栏菜单
  • [ ] 用户 / 角色 / 菜单管理页可打开
  • [ ] 无权限账号访问接口返回 403

下一步 ​

Xichen Full Stack 内部文档

Copyright © 2026