Skip to content

安装部署指南 ​

MengStack 采用 Monorepo 结构,包含后端 API(Go)、管理后台(开发中)和 Web 客户端(开发中)。本文档介绍从开发环境到 Docker 一键部署的完整流程。

项目结构 ​

mengstack/
├── api/                → 后端 API(Go/Gin)
├── admin/              → 超级管理员后台(开发中)
├── web/                → 客户端 Web(开发中)
├── docker-compose.yml  → 一键部署编排
└── .env.example        → 环境变量模板

环境要求 ​

依赖版本说明
Go1.26+编译运行后端 API
PostgreSQL16+主数据库
Redis7+缓存 / 限流 / 会话
Docker20+容器部署(可选)
Docker Composev2+编排部署(可选)

一键 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_PASSWORDPostgreSQL 密码修改默认值
JWT_SECRETJWT 签名密钥至少 32 字符

3. 启动服务 ​

bash
docker-compose up -d

4. 验证 ​

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就绪检查(含依赖)
Swaggerhttp://localhost:2222/swagger/index.htmlAPI 文档(仅 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=console

3. 编译运行 ​

bash
# 安装依赖
go mod download

# 运行(自动执行数据库迁移)
make run

# 或
go run ./cmd/server

服务启动时自动执行:

  1. 数据库迁移(核心表 + 插件表)
  2. RBAC 权限种子数据
  3. 插件初始化
  4. 事件总线 Worker 启动
  5. 定时任务调度器启动

4. 常用命令 ​

bash
make build       # 编译二进制到 build/
make test        # 运行测试
make test-cover  # 测试覆盖率报告
make swagger     # 重新生成 Swagger 文档
make lint        # 代码检查
make tidy        # go mod tidy

环境变量完整参考 ​

根目录 .env(Docker 部署) ​

变量默认值说明
SERVER_PORT2222API 服务端口
SERVER_MODEdebugdebug / release
DB_PORT5432PostgreSQL 端口
DB_USERpostgres数据库用户
DB_PASSWORDyour-secure-password-here数据库密码
DB_NAMEmengstack数据库名
REDIS_PORT6379Redis 端口
REDIS_PASSWORD(空)Redis 密码
REDIS_DB0Redis DB 编号
JWT_SECRETyour-jwt-secret-at-least-32-charsJWT 签名密钥
JWT_ACCESS_EXPIRY_MINUTES30Access Token 有效期(分钟)
JWT_REFRESH_EXPIRY_DAYS7Refresh Token 有效期(天)
JWT_ISSUERmengstackJWT 签发者标识
LOG_LEVELinfodebug / info / warn / error
LOG_FORMATjsonjson / console

api/.env(本地开发) ​

所有变量以 MENGSTACK_ 为前缀,其余同上。

编译部署 ​

编译二进制 ​

bash
cd api/
make build
# 输出: build/mengstack

运行 ​

bash
./build/mengstack

Docker 构建 ​

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

Released under the Apache 2.0 License.