星河避难所

返回

快速开始

本节将帮助你快速完成 OneAdmin 的环境准备、项目启动与基本访问配置。通过简单几步，你可以在本地运行完整的开发环境（前后端一体），并了解各服务入口与基础使用方式。

查看更多

环境要求#

依赖版本是否必需用途
Go≥ 1.25✅ 后端编译与运行
Node.js≥ 18✅ 仅开发环境前端构建工具链 (Vite)
Mysql 或 PostgreSQL主流版本✅ 任选其一数据库
Redis≥ 6.0⚠️ 可选用于 JWT 认证令牌的会话缓存

获取项目并初始化配置#

git clone https://github.com/zxc7563598/oneadmin.git
cd oneadmin
cp config.example.yaml config.yaml
bash

根据实际情况修改 config.yaml（如数据库连接等配置）。

启动开发环境#

推荐使用 Makefile 一键启动：

make dev
bash

该命令会同时启动：

  • Go 后端服务
  • 前端开发服务器（Vite）

可访问服务#

项目启动后，可访问以下服务：

服务名称地址说明
Go APIhttp://localhost:9000 ↗后端 REST API 服务
Vite Devhttp://localhost:5173 ↗前端开发服务器（支持热重载，并代理 API 请求到 :9000）
Swagger UIhttp://localhost:9000/swagger/index.html ↗交互式 API 文档（仅开发环境）
ReDochttp://localhost:9000/redoc ↗备用 API 文档查看器（仅开发环境）
管理后台http://localhost:9000/admin/ ↗构建后的前端页面（嵌入在后端服务中）

构建项目#

构建当前平台#

make build
bash

构建完成后，生成的可执行文件位于：

./bin/oneadmin
bash

构建前端资源#

make build-web
bash

构建后的前端资源会自动同步至：

internal/webui/dist
text

构建多平台版本#

make release
bash

支持以下平台：

  • Linux (amd64)
  • macOS (amd64 / arm64)
  • Windows (amd64)

运行服务#

./bin/oneadmin
bash

启动参数#

程序支持以下参数：

-port    服务端口（默认：9000）
-config  配置文件路径（默认：config.yaml）
text

示例#

# 使用默认配置
./bin/oneadmin

# 指定端口
./bin/oneadmin -port 8080

# 指定配置文件
./bin/oneadmin -config ./configs/dev.yaml

# 同时指定
./bin/oneadmin -port 8080 -config ./configs/dev.yaml
bash

其他常用命令#

# 生成 Swagger 文档
make swagger

# 清理构建产物
make clean
bash

说明#

  • 开发环境建议使用 make dev，可同时启动前后端并支持前端热更新
  • 生产环境建议使用 make build 构建后，通过二进制文件运行
  • Swagger UI 与 ReDoc 默认仅在非生产模式下启用
评论似乎卡住了，尝试刷新？✨