# wpms

**Repository Path**: wpfly2020/wpms

## Basic Information

- **Project Name**: wpms
- **Description**: WPMS 是一个基于 Go 语言的轻量级快速开发脚手架，集成了微信生态、实时通信、安全认证等常用功能模块。采用简洁的多进程架构，支持 Windows、Linux 和 ARM 多平台部署，提供公众号管理、小程序配置、微信支付、文件上传、WebSocket 实时推送等开箱即用的功能，适合快速构建小型管理系统和个人项目。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WPMS

![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)
![Go Version](https://img.shields.io/badge/go-1.24.0-brightgreen.svg)
![License](https://img.shields.io/badge/license-MIT-orange.svg)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20ARM-lightgrey.svg)

**基于 Go + Gin 框架开发的高效、安全的快速开发脚手架**

[快速开始](#-快速开始) • [功能特性](#-功能特性) • [技术架构](#-技术架构) • [API 文档](#-api-文档) • [部署指南](#-部署指南)

---

## 📖 项目简介

WPMS 是一个基于 Go 语言的轻量级快速开发脚手架，集成了微信生态、实时通信、安全认证等常用功能模块。采用简洁的多进程架构，支持 Windows、Linux 和 ARM 多平台部署，提供公众号管理、小程序配置、微信支付、文件上传、WebSocket 实时推送等开箱即用的功能，适合快速构建小型管理系统和个人项目。

## ✨ 功能特性

### 🚀 为什么选择 WPMS 脚手架？
- ✅ **开箱即用**: 预置完整的管理系统功能，无需从零开始
- ✅ **轻量简洁**: 代码结构清晰，易于理解和二次开发
- ✅ **小应用首选**: 专为小型项目设计，拒绝过度设计
- ✅ **丰富集成**: 微信生态、文件存储、实时通信等常用功能
- ✅ **单文件部署**: 所有资源（包括配置、https证书、rsa密钥、模板、其他前端静态资源等）内嵌到可执行文件
- ✅ **跨平台**: 一次开发，多平台部署

### 🔐 用户认证与安全
- ✅ **双模式登录**: 账号密码登录 + 微信扫码登录 (OAuth2)
- ✅ **多重加密**: RSA 传输加密 + AES 数据加密 + 密码哈希存储
- ✅ **会话管理**: 基于 Token 的认证机制，支持记住登录状态
- ✅ **流量控制**: 令牌桶算法防止恶意请求

### 💬 微信平台集成
- ✅ **公众号管理**: 密钥配置、菜单管理、消息回调、Token 管理
- ✅ **小程序支持**: AppID/Secret 配置、会话密钥获取
- ✅ **微信支付**: 支付密钥配置与管理
- ✅ **扫码登录**: 动态二维码生成、实时授权确认

### 🔌 WebSocket 实时通信
- ✅ **连接管理**: 客户端自动注册/注销、唯一连接 ID
- ✅ **消息推送**: 点对点推送、签名验证
- ✅ **实时通知**: 扫码登录授权结果实时推送

### 📤 文件管理
- ✅ **多文件上传**: 支持图片 (20MB)、文档 (50MB)
- ✅ **分类存储**: 按日期自动归档 (年/月/日)
- ✅ **安全验证**: 签名机制防止未授权上传
- ✅ **公私分离**: 公有文件访问 + 私有文件下载

### 🖥️ 后台管理系统
- ✅ **系统监控**: CPU、内存、运行时长实时监控
- ✅ **配置管理**: 动态配置站点信息、密钥管理
- ✅ **用户中心**: 个人资料修改、密码变更
- ✅ **多语言**: 中文/英文界面切换

### 🏗️ 技术架构

#### 核心技术栈
- **语言**: Go 1.24.0
- **Web 框架**: Gin v1.11.0
- **数据库**: Badger v4.2.0 (KV 存储)
- **WebSocket**: Gorilla WebSocket v1.5.0
- **配置解析**: go-ini v1.67.0
- **验证器**: validator/v10 v10.28.0
- **Gzip 压缩**: gin-contrib/gzip v1.2.5

#### 安全与性能特性
- ✅ **HTTPS/SSL**: 支持 TLS 加密传输，自动 HTTP→HTTPS 重定向
- ✅ **Gzip 压缩**: 自动压缩文本资源，提升加载速度（排除图片等已压缩格式）
- ✅ **多进程架构**: 主进程 + 守护进程 + 工作进程，高可用设计

### 系统架构
```
┌─────────────────────────────────────────┐
│          主进程 (Main Process)           │
│  - 版本检查                              │
│  - 端口检测                              │
│  - 派生守护进程                          │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│       守护进程 (Daemon Process)          │
│  - 监控工作进程                          │
│  - 自动重启异常退出的进程                │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│       工作进程 (Worker Process)          │
│  ┌──────────────────────────────────┐   │
│  │    Gin HTTP Server               │   │
│  │    - 路由注册                    │   │
│  │    - 中间件处理                  │   │
│  │    - 请求处理器                  │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │    WebSocket Server              │   │
│  │    - 连接管理                    │   │
│  │    - 消息推送                    │   │
│  └──────────────────────────────────┘   │
│  ┌──────────────────────────────────┐   │
│  │    数据存储                      │   │
│  │    - GoTable (B+ 树/哈希索引)     │   │
│  │    - Memcache (缓存)             │   │
│  │    - Badger (持久化)             │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

### 目录结构
```
wpms/
├── bin/                    # 编译输出目录
├── cert/                   # SSL 证书
├── config/                 # 配置文件
│   ├── config.go          # 配置加载逻辑
│   ├── config.ini         # 配置文件
│   └── config.ini.tpl     # 配置模板
├── internal/              # 内部包
│   ├── handlers/          # HTTP 请求处理器
│   ├── helper/            # 辅助函数
│   ├── middlewares/       # 中间件
│   ├── models/            # 数据模型
│   ├── resources/         # 静态资源
│   ├── router/            # 路由配置
│   └── templates/         # HTML 模板
├── pkg/                   # 公共包
│   ├── aes/               # AES 加密
│   ├── badger/            # Badger 封装
│   ├── bucket/            # 令牌桶限流
│   ├── gotable/           # 内存数据表
│   ├── memcache/          # 内存缓存
│   ├── rsa/               # RSA 加密
│   ├── setting/           # 动态配置
│   ├── storage/           # 数据持久化
│   ├── utils/             # 工具函数
│   └── wechat/            # 微信 SDK
├── tools/                 # 构建工具脚本
├── main.go                # 程序入口
└── go.mod                 # Go 模块依赖
```

## 🚀 快速开始

### 环境要求
- Go 1.24.0 或更高版本
- Git
- Bash (Windows 推荐安装 Git Bash)

### 安装步骤

#### 1. 克隆项目
```bash
git clone https://gitee.com/wpfly2020/wpms.git
cd wpms
```

#### 2. 安装依赖
```bash
go mod download
```

#### 3. 构建项目

**一键构建所有平台:**
```bash
cd tools
./build_all.sh
```

**单独构建特定平台:**

**Windows**
```bash
cd tools
./build_windows.sh
```

**Linux**
```bash
cd tools
./build_linux.sh
```

**ARM (树莓派等)**
```bash
cd tools
./build_arm.sh
```

#### 4. 运行程序

**调试运行（开发环境）：**

使用项目提供的测试脚本，自动完成构建并立即运行：
```bash
cd tools
./test_windows.sh    # Windows
./test_linux.sh      # Linux
```

![调试运行示例](docs/images/debug_run.png)
*调试运行示意图*

**正式运行（生产环境）：**

直接运行编译好的程序：
```bash
cd bin
./wpms_windows_amd64.exe  # Windows
./wpms_linux_amd64        # Linux
```

**带参数运行:**
```bash
./wpms_windows_amd64.exe --ip=0.0.0.0 --port=8080
```

### 首次使用

1. **访问管理后台**: `http://localhost:8080`
2. **默认登录密码**: 查看 `config/config.ini` 中的 `LOGIN_PASSWORD` 配置
3. **修改密码**: 登录后进入「用户管理」→「安全设置」

![登录页面](docs/images/login_page.png)
*图 1：管理后台登录页面*

![系统首页](docs/images/system_index.png)
*图 2：系统管理首页*

## 📡 API 文档

### 认证相关

#### 管理员登录
```http
POST /management/login.html
Content-Type: application/x-www-form-urlencoded

username=admin&password=<RSA_ENCRYPTED>&remember=on
```

#### 退出登录
```http
POST /management/logout.html
```

### 微信管理

#### 保存微信公众号密钥
```http
POST /management/api/wechat/keys
Authorization: Bearer <token>

{
  "appid": "wx1234567890",
  "appsecret": "your-app-secret"
}
```

#### 获取微信公众号菜单
```http
POST /management/api/wechat/menu/get
Authorization: Bearer <token>
```

#### 推送微信公众号菜单
```http
POST /management/api/wechat/menu/push
Authorization: Bearer <token>

{
  "menu": {...}
}
```

### 用户管理

#### 修改个人资料
```http
POST /management/api/user/save_profile
Authorization: Bearer <token>

nickname=张三&avatar=/upload/images/20260401/xx/avatar.jpg
```

#### 修改密码
```http
POST /management/api/user/change_password
Authorization: Bearer <token>

current_password=old_password&new_password=new_password
```

### WebSocket

#### 建立 WebSocket 连接
```javascript
const ws = new WebSocket('ws://localhost:8080/websocket');

ws.onopen = () => {
  console.log('WebSocket 连接已建立');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.action === 'connected') {
    console.log('连接 ID:', data.data);
  }
};
```

#### 推送 WebSocket 消息
```http
POST /api/websocket/push
Content-Type: application/json

{
  "app_id": "your-app-id",
  "timestamp": "1234567890",
  "signature": "<SIGNATURE>",
  "client_id": "<CLIENT_ID>",
  "message": "Hello WebSocket"
}
```

### 文件上传

#### 上传图片
```http
POST /api/upload
Content-Type: multipart/form-data

timestamp=1234567890
config=images
signature=<SIGNATURE>
file=@image.jpg
```

**签名生成示例 (Go):**
```go
data := map[string]string{
  "timestamp": "1234567890",
  "config":    "images",
}
signature := utils.SignData(data, uploadKey)
```

## 🛠️ 部署指南

### 🚀 一键部署（推荐）

WPMS 提供了自动化部署脚本，可一键完成构建和系统服务安装：

```
# 本地执行发布脚本
cd tools
./publish.sh

# 将发布包上传到服务器
scp -r ../publish/wpms user@server:/opt/

# 登录服务器并安装服务
ssh user@server
cd /opt/wpms
sudo ./install_service.sh
```

安装完成后，服务会自动启动并开机自启。使用 `systemctl status wpms` 查看服务状态。

---

### 手动部署

#### Linux 系统服务安装

#### 1. 上传文件
将编译好的程序上传到服务器:
```bash
scp wpms_linux_amd64 user@server:/opt/wpms/
```

#### 2. 创建 systemd 服务
```bash
sudo vim /etc/systemd/system/wpms.service
```

内容:
```ini
[Unit]
Description=WPMS Service
After=network.target

[Service]
Type=forking
ExecStart=/opt/wpms/wpms_linux_amd64 --port=8080
WorkingDirectory=/opt/wpms
Restart=always
User=www-data
Group=www-data

[Install]
WantedBy=multi-user.target
```

#### 3. 启动服务
```bash
sudo systemctl daemon-reload
sudo systemctl enable wpms
sudo systemctl start wpms
sudo systemctl status wpms
```

### Docker 部署 (可选)

```dockerfile
FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o wpms .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/wpms .
EXPOSE 8080
CMD ["./wpms"]
```

构建并运行:
```bash
docker build -t wpms .
docker run -p 8080:8080 wpms
```

---

### 🔒 HTTPS/SSL 配置

#### 启用 HTTPS

在 `config/config.ini` 中启用 SSL：

```ini
[server]
ENABLE_SSL = true    # 启用 HTTPS，自动监听 443 端口和 80 端口（重定向）
```

**特性说明：**
- ✅ **自动监听 443 端口**: HTTPS 服务
- ✅ **自动监听 80 端口**: HTTP 自动重定向到 HTTPS（301 永久重定向）
- ✅ **证书管理**: 证书文件放在 `cert/` 目录下（`www.example.com.crt` + `www.example.com.key`）
- ✅ **Gzip 压缩**: 自动启用，智能排除图片等已压缩资源

#### 证书生成

使用项目提供的脚本生成自签名证书（开发环境）：
```bash
cd tools
./create_cert.sh
```

**生产环境建议使用：**
- Let's Encrypt 免费证书
- 阿里云 SSL 证书
- 腾讯云 SSL 证书

## ⚙️ 配置说明

### config.ini 配置文件

```ini
[server]
IP = 0.0.0.0              # 监听地址
PORT = 8080               # 监听端口
LIFE_MONTHS = 18          # 程序有效期 (月)
DEBUG_MODE = false        # 调试模式
ENABLE_SSL = false        # 是否启用 HTTPS

[management]
LOGIN_COOKIE_NAME = management_token
LOGIN_PASSWORD = <HASHED_PASSWORD>  # 哈希密码

[bucket]
CAPACITY = 10             # 令牌桶容量
INTERVAL = 300            # 令牌补充间隔 (秒)
COUNT_PER_TIME = 1        # 每次补充数量

[setting]
FILE_NAME = setting.db    # 动态配置文件名
PASSWORD = your-key       # 加密密钥

[upload]
ENABLED = 1               # 是否启用上传功能
```

### 环境变量

可以通过环境变量覆盖配置:
```bash
export WPMS_PORT=9000
export WPMS_DEBUG_MODE=true
```

## 🔒 安全建议

1. **修改默认密码**: 首次运行后立即修改默认密码
2. **启用 HTTPS**: 生产环境务必启用 SSL
3. **防火墙配置**: 仅开放必要端口
4. **定期备份**: 定期备份 `bin/setting.db`
5. **日志监控**: 定期检查 `daemon.log` 和 `worker.log`

## 📊 性能优化

### 内存优化
- 调整令牌桶容量减少并发压力
- 合理配置 Memcache 缓存策略

### 数据库优化
- 使用 B+ 树索引加速时间范围查询
- 使用哈希索引加速精确匹配查询

### WebSocket 优化
- 限制单个客户端消息频率
- 实现心跳检测机制

## 🐛 常见问题

### Q1: 端口被占用
**解决方案**: 修改 `config.ini` 中的 `PORT` 或使用 `--port` 参数指定其他端口

***（注意：修改config.ini配置文件后，需重新打包）***

### Q2: 程序过期
**解决方案**: 修改 `config.ini` 中 `LIFE_MONTHS=-1` 永久有效，或重新编译

### Q3: WebSocket 连接失败
**解决方案**: 
- 检查防火墙是否放行端口
- 确认签名密钥配置正确
- 查看浏览器控制台错误信息

### Q4: 文件上传失败
**解决方案**:
- 检查 `upload.ENABLED=1`
- 确认上传密钥已配置
- 检查文件类型和大小限制

## 📝 更新日志

### v2.0.0 (2026-04-01)
- ✨ 新增 WebSocket 实时通信模块
- ✨ 新增微信扫码登录功能
- ✨ 新增文件上传签名验证
- 🔧 优化多进程架构
- 🐛 修复已知安全问题

### v1.x.x
- 🎉 初始版本发布
- 📦 基础管理功能
- 🔐 用户认证系统

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request!

1. Fork 本项目（Gitee）
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request（Gitee）

## 📄 开源协议

本项目采用 MIT 协议开源

## 📞 联系方式

- **作者**: wpfly
- **邮箱**: wpfly2020@qq.com
- **项目地址**: https://gitee.com/wpfly2020/wpms

## 🙏 致谢

感谢以下开源项目:
- [Gin Framework](https://github.com/gin-gonic/gin)
- [Badger DB](https://github.com/dgraph-io/badger)
- [Gorilla WebSocket](https://github.com/gorilla/websocket)

---

**如果这个项目对你有帮助，请给一个 ⭐️ Star 支持！**

Made with ❤️ by WPMS Team