feat: add docs pages

This commit is contained in:
Your Name
2025-11-18 18:29:15 +08:00
parent 953f744846
commit 1b00ed8bb9
22 changed files with 4547 additions and 0 deletions
+151
View File
@@ -0,0 +1,151 @@
# 开发调试
本文档介绍如何在开发环境中运行 Message Nest。
## 前置要求
- Go 1.18+
- Node.js 16+
- MySQL 5.7+ 或 SQLite
## 部署步骤
### 1. 克隆项目
```bash
git clone https://github.com/engigu/Message-Push-Nest.git
cd Message-Push-Nest
```
### 2. 配置文件
重命名 `conf/app.example.ini``conf/app.ini`,关键配置如下:
```ini
[app]
JwtSecret = message-nest
LogLevel = INFO
[server]
; RunMode务必设置成debug,会自动添加跨域
RunMode = debug
HttpPort = 8000
ReadTimeout = 60
WriteTimeout = 60
; 取消EmbedHtml的注释(启用前后端分离),然后到web目录下面,npm run dev启动前端页面
EmbedHtml = disable
[database]
; 开启SQL打印
SqlDebug = enable
; Type = sqlite
Type = mysql
User = root
Password = Aa123456
Host = vm.server
Port = 3308
Name = yourDbName
TablePrefix = message_
```
::: warning 重要配置
- `RunMode` 必须设置为 `debug`,会自动添加跨域
- `EmbedHtml` 必须取消注释,启用前后端分离
- `SqlDebug` 建议启用,方便调试
:::
### 3. 启动后端服务
```bash
go mod tidy
go run main.go
```
服务启动后会运行在8000端口。
### 4. 启动前端服务
```bash
cd web
npm i
npm run dev
```
页面启动后会提示访问URL,一般是 `http://127.0.0.1:5173`
### 5. 访问应用
访问 `http://127.0.0.1:5173`,进行调试开发。
接口会自动转发到go服务 `http://localhost:8000`
## 开发说明
### 目录结构
```
Message-Push-Nest/
├── conf/ # 配置文件
├── middleware/ # 中间件
├── migrate/ # 数据库迁移
├── models/ # 数据模型
├── pkg/ # 工具包
├── routers/ # 路由
├── service/ # 业务逻辑
├── web/ # 前端项目
│ ├── src/ # 源代码
│ ├── public/ # 静态资源
│ └── dist/ # 构建输出
└── main.go # 入口文件
```
### 前端技术栈
- Vue 3
- TypeScript
- Vite
- TailwindCSS
- shadcn-vue
### 后端技术栈
- Go
- Gin
- GORM
- Logrus
## 构建生产版本
### 构建前端
```bash
cd web
npm run build
```
构建产物会输出到 `web/dist` 目录。
### 构建后端
```bash
CGO_ENABLED=0 go build -o Message-Nest
```
## 常见问题
### 前端无法连接后端
检查 `web/vite.config.ts` 中的代理配置是否正确。
### 热更新不生效
1. 检查文件是否保存
2. 重启前端开发服务器
3. 清除浏览器缓存
### 数据库连接失败
1. 检查数据库服务是否启动
2. 检查配置文件中的连接信息
3. 检查数据库用户权限
+112
View File
@@ -0,0 +1,112 @@
# 直接运行
使用最新的Release打包的可执行文件部署,无需部署前端页面。
::: tip 推荐指数
🍀🍀🍀🍀 适合没有Docker环境的生产部署
:::
## 部署步骤
### 1. 下载Release
访问 [GitHub Releases](https://github.com/engigu/Message-Push-Nest/releases) 下载最新的系统版本对应的release,然后解压。
### 2. 创建数据库
新建一个MySQL数据库(或使用SQLite)。
### 3. 配置文件
重命名 `conf/app.example.ini``conf/app.ini`,然后修改配置:
```ini
[app]
JwtSecret = message-nest
LogLevel = INFO
[server]
RunMode = release
HttpPort = 8000
ReadTimeout = 60
WriteTimeout = 60
; 注释EmbedHtml,启用单应用模式
; EmbedHtml = disable
[database]
; 关闭SQL打印
; SqlDebug = enable
; Type = sqlite
Type = mysql
User = root
Password = Aa123456
Host = vm.server
Port = 3308
Name = yourDbName
TablePrefix = message_
```
::: warning 重要
将配置中 `EmbedHtml = disable` 进行注释,以单应用方式运行。
:::
### 4. 启动项目
直接运行可执行文件,项目会自动创建表和账号。
```bash
# Windows
./Message-Nest.exe
# Linux/Mac
./Message-Nest
```
### 5. 查看日志
INFO日志级别启动会出现如下日志:
```log
[2024-01-13 13:40:09.075] INFO [migrate.go:70 Setup] [Init Data]: Migrate table: message_auth
[2024-01-13 13:40:11.778] INFO [migrate.go:70 Setup] [Init Data]: Migrate table: message_send_tasks
[2024-01-13 13:40:16.518] INFO [migrate.go:70 Setup] [Init Data]: Migrate table: message_send_ways
[2024-01-13 13:40:23.300] INFO [migrate.go:70 Setup] [Init Data]: Migrate table: message_send_tasks_logs
[2024-01-13 13:40:28.715] INFO [migrate.go:70 Setup] [Init Data]: Migrate table: message_send_tasks_ins
[2024-01-13 13:40:39.538] INFO [migrate.go:70 Setup] [Init Data]: Migrate table: message_settings
[2024-01-13 13:40:46.299] INFO [migrate.go:74 Setup] [Init Data]: Init Account data...
[2024-01-13 13:40:46.751] INFO [migrate.go:77 Setup] [Init Data]: All table data init done.
```
### 6. 访问服务
访问 `http://localhost:8000`
- 默认账号:`admin`
- 默认密码:`123456`
## 使用SQLite
如果不想安装MySQL,可以使用SQLite
```ini
[database]
Type = sqlite
TablePrefix = message_
```
SQLite数据库文件会自动创建在 `conf/database.db`
## 常见问题
### 启动失败
1. 检查端口8000是否被占用
2. 检查数据库连接配置是否正确
3. 查看日志输出的错误信息
### 无法访问页面
1. 确认服务已正常启动
2. 检查防火墙设置
3. 确认 `EmbedHtml` 配置已注释
+240
View File
@@ -0,0 +1,240 @@
# Docker Compose 部署
使用 Docker Compose 编排部署 Message Nest。
::: tip 推荐指数
🍀🍀🍀🍀🍀 适合生产环境,便于管理
:::
## 方式一:挂载配置文件
### 1. 准备配置文件
创建 `conf/app.ini`,内容参考 [Docker部署](/deployment/docker#_1-准备配置文件)。
### 2. 创建 docker-compose.yml
```yaml
version: "3.7"
services:
message-nest:
image: engigu/message-nest:latest
# 或使用 GHCR 镜像
# image: ghcr.io/engigu/message-nest:latest
container_name: message-nest
restart: always
volumes:
- ./conf:/app/conf
ports:
- "8000:8000"
```
### 3. 文件目录结构
```
.
├── conf
│ └── app.ini
└── docker-compose.yml
```
### 4. 启动服务
```bash
# 测试运行
docker-compose up
# 正式运行(后台)
docker-compose up -d
```
## 方式二:环境变量(推荐)
### 使用 MySQL
创建 `docker-compose.yml`
```yaml
version: "3.7"
services:
message-nest:
image: engigu/message-nest:latest
# 或使用 GHCR 镜像
# image: ghcr.io/engigu/message-nest:latest
container_name: message-nest
restart: always
ports:
- "8000:8000"
environment:
- MYSQL_HOST=192.168.64.133
- MYSQL_PORT=3308
- MYSQL_USER=root
- MYSQL_PASSWORD=Aa123456
- MYSQL_DB=test_11
- MYSQL_TABLE_PREFIX=message_
```
### 使用 SQLite
创建 `docker-compose.yml`
```yaml
version: "3.7"
services:
message-nest:
image: engigu/message-nest:latest
# 或使用 GHCR 镜像
# image: ghcr.io/engigu/message-nest:latest
container_name: message-nest
restart: always
ports:
- "8000:8000"
volumes:
- ./data/database.db:/app/conf/database.db
```
### 启动服务
```bash
# 正式运行
docker-compose up -d
```
## 完整示例:MySQL + Message Nest
如果你还没有MySQL,可以使用以下配置同时部署MySQL和Message Nest
```yaml
version: "3.7"
services:
mysql:
image: mysql:8.0
container_name: message-nest-mysql
restart: always
environment:
- MYSQL_ROOT_PASSWORD=Aa123456
- MYSQL_DATABASE=message_nest
volumes:
- mysql-data:/var/lib/mysql
ports:
- "3306:3306"
message-nest:
image: engigu/message-nest:latest
container_name: message-nest
restart: always
depends_on:
- mysql
ports:
- "8000:8000"
environment:
- MYSQL_HOST=mysql
- MYSQL_PORT=3306
- MYSQL_USER=root
- MYSQL_PASSWORD=Aa123456
- MYSQL_DB=message_nest
- MYSQL_TABLE_PREFIX=message_
volumes:
mysql-data:
```
## 常用命令
### 启动服务
```bash
# 前台启动(查看日志)
docker-compose up
# 后台启动
docker-compose up -d
```
### 查看日志
```bash
# 查看所有服务日志
docker-compose logs
# 查看特定服务日志
docker-compose logs message-nest
# 实时查看日志
docker-compose logs -f message-nest
```
### 停止服务
```bash
# 停止服务
docker-compose stop
# 停止并删除容器
docker-compose down
# 停止并删除容器和数据卷
docker-compose down -v
```
### 重启服务
```bash
# 重启所有服务
docker-compose restart
# 重启特定服务
docker-compose restart message-nest
```
### 更新镜像
```bash
# 拉取最新镜像
docker-compose pull
# 重新创建容器
docker-compose up -d
```
## 访问服务
启动后访问 `http://localhost:8000`
- 默认账号:`admin`
- 默认密码:`123456`
## 常见问题
### 服务无法启动
1. 检查端口是否被占用
2. 检查配置是否正确
3. 查看日志:`docker-compose logs`
### MySQL连接失败
1. 确保MySQL服务已启动
2. 检查 `MYSQL_HOST` 是否正确(使用服务名)
3. 等待MySQL完全启动(约10-30秒)
### 数据持久化
使用volumes确保数据持久化:
```yaml
volumes:
- ./data:/app/conf # 配置文件
- mysql-data:/var/lib/mysql # MySQL数据
```
### 修改配置后重启
```bash
# 修改配置文件或环境变量后
docker-compose down
docker-compose up -d
```
+201
View File
@@ -0,0 +1,201 @@
# Docker 部署
使用 Docker 部署 Message Nest,支持多种配置方式。
::: tip 推荐指数
🍀🍀🍀🍀🍀 最推荐的部署方式
:::
## 镜像源
Message Nest 提供两个镜像源:
- **Docker Hub**: `engigu/message-nest:latest`
- **GitHub Container Registry**: `ghcr.io/engigu/message-nest:latest`
## 方式一:挂载配置文件
### 1. 准备配置文件
新建 `conf/app.ini` 文件:
```ini
[app]
JwtSecret = message-nest
LogLevel = INFO
[server]
RunMode = release
; docker模式下端口配置文件中只能为8000
HttpPort = 8000
ReadTimeout = 60
WriteTimeout = 60
; 注释EmbedHtml,启用单应用模式
; EmbedHtml = disable
[database]
; 关闭SQL打印
; SqlDebug = enable
; Type = sqlite
Type = mysql
User = root
Password = Aa123456
Host = vm.server
Port = 3308
Name = yourDbName
TablePrefix = message_
```
::: warning 端口限制
Docker模式下,配置文件中的端口只能为8000,通过 `-p` 参数映射到宿主机端口。
:::
### 2. 拉取镜像
```bash
# 从 Docker Hub 拉取
docker pull engigu/message-nest:latest
# 或从 GitHub Container Registry (GHCR) 拉取
docker pull ghcr.io/engigu/message-nest:latest
```
### 3. 启动容器
```bash
# 测试运行(Docker Hub 镜像)
docker run --rm -ti \
-p 8000:8000 \
-v /your/path/conf:/app/conf \
engigu/message-nest:latest
# 测试运行(GHCR 镜像)
docker run --rm -ti \
-p 8000:8000 \
-v /your/path/conf:/app/conf \
ghcr.io/engigu/message-nest:latest
# 正式运行(Docker Hub 镜像)
docker run -d \
-p 8000:8000 \
-v /your/path/conf:/app/conf \
engigu/message-nest:latest
# 正式运行(GHCR 镜像)
docker run -d \
-p 8000:8000 \
-v /your/path/conf:/app/conf \
ghcr.io/engigu/message-nest:latest
```
## 方式二:环境变量(推荐)
::: tip 推荐
这是最简单的部署方式,无需准备配置文件。
:::
### 环境变量说明
| 变量 | 说明 |
|------|------|
| JWT_SECRET | jwt秘钥,可选,默认为message-nest |
| LOG_LEVEL | 日志等级,可选,默认为INFODEBUG/INFO/ERROR |
| RUN_MODE | 运行模式,可选,默认release,为debug将自动添加跨域 |
| DB_TYPE | 数据库类型,sqlite/mysql。默认为sqlite,存储路径为conf/database.db |
| MYSQL_HOST | mysql-hostDB_TYPE=mysql必填 |
| MYSQL_PORT | mysql端口,DB_TYPE=mysql必填 |
| MYSQL_USER | mysql用户名,DB_TYPE=mysql必填 |
| MYSQL_PASSWORD | mysql数据库密码,DB_TYPE=mysql必填 |
| MYSQL_DB | mysql数据库名字,DB_TYPE=mysql必填 |
| MYSQL_TABLE_PREFIX | mysql数据表前缀,DB_TYPE=mysql必填 |
| SSL | 是否开启SSL |
| SQL_DEBUG | 是否打印SQL,可选,默认关,设置enable为开启 |
### 使用 MySQL
```bash
# 正式运行(mysql
docker run -d \
-p 8000:8000 \
-e MYSQL_HOST=192.168.64.133 \
-e MYSQL_PORT=3308 \
-e MYSQL_USER=root \
-e MYSQL_PASSWORD=Aa123456 \
-e MYSQL_DB=test_11 \
-e MYSQL_TABLE_PREFIX=message_ \
--name message-nest \
engigu/message-nest:latest
# 或使用 GHCR 镜像(mysql
docker run -d \
-p 8000:8000 \
-e MYSQL_HOST=192.168.64.133 \
-e MYSQL_PORT=3308 \
-e MYSQL_USER=root \
-e MYSQL_PASSWORD=Aa123456 \
-e MYSQL_DB=test_11 \
-e MYSQL_TABLE_PREFIX=message_ \
--name message-nest \
ghcr.io/engigu/message-nest:latest
```
### 使用 SQLite
```bash
# 正式运行(sqlite
docker run -d \
-p 8000:8000 \
-v /your/path/database.db:/app/conf/database.db \
--name message-nest \
engigu/message-nest:latest
# 或使用 GHCR 镜像(sqlite
docker run -d \
-p 8000:8000 \
-v /your/path/database.db:/app/conf/database.db \
--name message-nest \
ghcr.io/engigu/message-nest:latest
```
## 访问服务
启动后访问 `http://localhost:8000`
- 默认账号:`admin`
- 默认密码:`123456`
## 常见问题
### 容器无法启动
1. 检查端口是否被占用
2. 检查数据库连接配置
3. 查看容器日志:`docker logs message-nest`
### 数据持久化
使用SQLite时,记得挂载数据库文件:
```bash
-v /your/path/database.db:/app/conf/database.db
```
### 查看日志
```bash
# 查看实时日志
docker logs -f message-nest
# 查看最近100行日志
docker logs --tail 100 message-nest
```
### 停止和删除容器
```bash
# 停止容器
docker stop message-nest
# 删除容器
docker rm message-nest
```
+53
View File
@@ -0,0 +1,53 @@
# 部署概览
Message Nest 提供多种部署方式,您可以根据自己的需求选择合适的部署方案。
## 部署方式对比
| 部署方式 | 难度 | 推荐指数 | 适用场景 |
|---------|------|---------|---------|
| Docker环境变量 | ⭐ | ⭐⭐⭐⭐⭐ | 生产环境,快速部署 |
| Docker Compose | ⭐ | ⭐⭐⭐⭐⭐ | 生产环境,编排部署 |
| 直接运行Release | ⭐⭐ | ⭐⭐⭐⭐ | 生产环境,无Docker环境 |
| 开发调试 | ⭐⭐⭐ | ⭐⭐⭐ | 开发环境 |
## 快速选择
### 我想快速体验
推荐使用 **Docker环境变量部署**,一条命令即可启动。
### 我要用于生产环境
推荐使用 **Docker Compose部署**,便于管理和维护。
### 我没有Docker环境
推荐使用 **直接运行Release**,下载可执行文件即可。
### 我要进行开发
推荐使用 **开发调试模式**,支持热更新。
## 默认账号
所有部署方式启动后,默认账号信息:
- 用户名:`admin`
- 密码:`123456`
::: warning 安全提示
首次登录后请立即修改默认密码!
:::
## 数据库选择
Message Nest 支持多种数据库:
- **SQLite** - 轻量级,无需额外配置,适合小规模使用
- **MySQL 5.x / 8.x** - 成熟稳定,适合中大规模使用
- **TiDB** - 分布式数据库,适合大规模使用
## 下一步
选择适合您的部署方式:
- [直接运行](/deployment/direct-run)
- [开发调试](/deployment/development)
- [Docker部署](/deployment/docker)
- [Docker Compose](/deployment/docker-compose)