Appearance
安装部署指南
MengStack 采用 Monorepo 结构,包含后端 API(Go)、管理后台(开发中)和 Web 客户端(开发中)。本文档介绍从开发环境到 Docker 一键部署的完整流程。
项目结构
mengstack/
├── api/ → 后端 API(Go/Gin)
├── admin/ → 超级管理员后台(开发中)
├── web/ → 客户端 Web(开发中)
├── docker-compose.yml → 一键部署编排
└── .env.example → 环境变量模板环境要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| Go | 1.26+ | 编译运行后端 API |
| PostgreSQL | 16+ | 主数据库 |
| Redis | 7+ | 缓存 / 限流 / 会话 |
| Docker | 20+ | 容器部署(可选) |
| Docker Compose | v2+ | 编排部署(可选) |
一键 Docker 部署
最快的部署方式,自动启动 PostgreSQL + Redis + API 三个服务。
1. 获取发行版
bash
# 克隆纯内核基座(9 大核心模块 + 示例插件,不含业务插件,可独立编译启动)
git clone https://mengstackgit.softunis.com/softunis/mengstack-kernel-dist.git
cd mengstack-kernel-dist发行版说明
- mengstack-kernel-dist:纯内核基座——认证 / 权限 / 组织 / 审计 / 配置 / 通知 / 仪表盘 / 菜单 / 用户 九大核心模块 + 示例插件,不含业务插件
- mengstack-plugin-{name}-dist:各业务插件(CMS / 媒体 / 搜索 / 会员等)独立发行,按需引入
- mengstack-admin-dist:管理后台前端
- 发行版均为公开仓库,无需认证即可克隆
2. 配置环境变量
bash
cp .env.example .env编辑 .env,必须修改以下两项:
| 变量 | 说明 | 要求 |
|---|---|---|
DB_PASSWORD | PostgreSQL 密码 | 修改默认值 |
JWT_SECRET | JWT 签名密钥 | 至少 32 字符 |
3. 启动服务
bash
docker-compose up -d4. 验证
bash
# 查看服务状态
docker-compose ps
# 健康检查
curl http://localhost:2222/health
# 版本信息
curl http://localhost:2222/api/version| 端点 | 地址 | 说明 |
|---|---|---|
| API 服务 | http://localhost:2222 | 主服务 |
| 健康检查 | http://localhost:2222/health | 存活探针 |
| 就绪探针 | http://localhost:2222/readyz | 就绪检查(含依赖) |
| Swagger | http://localhost:2222/swagger/index.html | API 文档(仅 debug 模式) |
5. 停止服务
bash
docker-compose down # 停止容器,保留数据
docker-compose down -v # 停止并删除数据卷(清除数据)本地开发
不使用 Docker,直接在本地运行后端 API。
1. 启动 PostgreSQL 和 Redis
使用 Docker 启动依赖服务:
bash
docker-compose up -d postgres redis或本地安装 PostgreSQL 16 和 Redis 7。
2. 配置后端
bash
cd api/
cp .env.example .env编辑 api/.env:
ini
# 服务
MENGSTACK_SERVER_PORT=2222
MENGSTACK_SERVER_MODE=debug
# PostgreSQL
MENGSTACK_DATABASE_HOST=127.0.0.1
MENGSTACK_DATABASE_PORT=5432
MENGSTACK_DATABASE_USER=postgres
MENGSTACK_DATABASE_PASSWORD=
MENGSTACK_DATABASE_DBNAME=mengstack
MENGSTACK_DATABASE_SSLMODE=disable
# Redis
MENGSTACK_REDIS_ADDR=127.0.0.1:6379
MENGSTACK_REDIS_PASSWORD=
MENGSTACK_REDIS_DB=0
# JWT(开发环境可用默认值,生产必须修改)
MENGSTACK_JWT_SECRET=change-me-in-production
MENGSTACK_JWT_ACCESS_EXPIRY_MINUTES=30
MENGSTACK_JWT_REFRESH_EXPIRY_DAYS=7
MENGSTACK_JWT_ISSUER=mengstack
# 日志
MENGSTACK_LOG_LEVEL=debug
MENGSTACK_LOG_FORMAT=console3. 编译运行
bash
# 安装依赖
go mod download
# 运行(自动执行数据库迁移)
make run
# 或
go run ./cmd/server服务启动时自动执行:
- 数据库迁移(核心表 + 插件表)
- RBAC 权限种子数据
- 插件初始化
- 事件总线 Worker 启动
- 定时任务调度器启动
4. 常用命令
bash
make build # 编译二进制到 build/
make test # 运行测试
make test-cover # 测试覆盖率报告
make swagger # 重新生成 Swagger 文档
make lint # 代码检查
make tidy # go mod tidy环境变量完整参考
根目录 .env(Docker 部署)
| 变量 | 默认值 | 说明 |
|---|---|---|
SERVER_PORT | 2222 | API 服务端口 |
SERVER_MODE | debug | debug / release |
DB_PORT | 5432 | PostgreSQL 端口 |
DB_USER | postgres | 数据库用户 |
DB_PASSWORD | your-secure-password-here | 数据库密码 |
DB_NAME | mengstack | 数据库名 |
REDIS_PORT | 6379 | Redis 端口 |
REDIS_PASSWORD | (空) | Redis 密码 |
REDIS_DB | 0 | Redis DB 编号 |
JWT_SECRET | your-jwt-secret-at-least-32-chars | JWT 签名密钥 |
JWT_ACCESS_EXPIRY_MINUTES | 30 | Access Token 有效期(分钟) |
JWT_REFRESH_EXPIRY_DAYS | 7 | Refresh Token 有效期(天) |
JWT_ISSUER | mengstack | JWT 签发者标识 |
LOG_LEVEL | info | debug / info / warn / error |
LOG_FORMAT | json | json / console |
api/.env(本地开发)
所有变量以 MENGSTACK_ 为前缀,其余同上。
编译部署
编译二进制
bash
cd api/
make build
# 输出: build/mengstack运行
bash
./build/mengstackDocker 构建
bash
cd api/
docker build -t mengstack:latest .API 目录自带 Dockerfile:
dockerfile
FROM golang:1.26-alpine AS builder
WORKDIR /build
COPY . .
RUN go mod download
RUN CGO_ENABLED=0 go build -o mengstack ./cmd/server
FROM alpine:3.19
RUN apk --no-cache add ca-certificates tzdata
WORKDIR /app
COPY --from=builder /build/mengstack .
EXPOSE 2222
CMD ["./mengstack"]演示站
- API:
https://mengstackdemo.softunis.com - Swagger:
https://mengstackdemo.softunis.com/swagger/index.html

