zhilv
e8c641414e
- 基于 Gin 框架搭建 HTTP 服务，接收并处理 Bot 命令请求 - 实现插件化命令系统，支持通过 Plugin 接口扩展新命令 - 内置菜单、启用/禁用、时间查询等基础命令 - 新增图片生成插件，对接 OpenAI Images API - 支持管理员权限控制、命令动态启禁用 - 提供完整配置管理（.env）与 Docker 部署方案
174 lines
4.0 KiB
Markdown
174 lines
4.0 KiB
Markdown
# NcatBot Command Server
|
||
|
||
基于 Go 的 Bot 命令处理服务器，支持插件化扩展命令。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
command-server/
|
||
├── main.go # 入口
|
||
├── config/
|
||
│ └── config.go # 配置加载（从 .env）
|
||
├── command/
|
||
│ ├── types.go # 共享类型（Req, Resp, Message）
|
||
│ ├── plugin.go # Plugin 接口定义
|
||
│ ├── registry.go # 命令注册表
|
||
│ ├── admin.go # 管理员权限检查
|
||
│ ├── init.go # 内置命令初始化
|
||
│ └── builtin.go # 内置命令（菜单/启用/禁用/时间）
|
||
├── plugins/
|
||
│ ├── plugins.go # 统一导入所有插件
|
||
│ └── image/
|
||
│ └── image.go # 图片生成插件
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
├── .env # 环境变量配置
|
||
└── .env.example # 配置模板
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 本地运行
|
||
|
||
```bash
|
||
# 安装依赖
|
||
go mod download
|
||
|
||
# 复制配置文件并填写
|
||
cp .env.example .env
|
||
|
||
# 运行
|
||
go run .
|
||
```
|
||
|
||
### Docker 运行
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
|
||
docker login gitea.kmux.cn
|
||
docker buildx build --platform linux/amd64,linux/arm64 -t gitea.kmux.cn/ncatbot/command-server:0.0.1 --no-cache .
|
||
docker push gitea.kmux.cn/ncatbot/command-server:0.0.1
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
复制 `.env.example` 为 `.env`，按需修改：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `SERVER_ADDR` | `127.0.0.1:8000` | 服务监听地址 |
|
||
| `OPENAI_API_KEY` | - | OpenAI API 密钥 |
|
||
| `OPENAI_BASE_URL` | `https://api.openai.com` | API 基础地址 |
|
||
| `OPENAI_MODEL` | `gpt-image-2` | 图片生成模型 |
|
||
| `REQUEST_TIMEOUT` | `120` | 请求超时（秒） |
|
||
| `IMAGE_COUNT` | `1` | 单次生成图片数 |
|
||
| `IMAGE_OUTPUT_DIR` | `images` | 图片本地暂存目录 |
|
||
| `UPLOAD_URL` | - | 图片上传接口地址 |
|
||
| `UPLOAD_API_KEY` | - | 上传接口 API Key |
|
||
| `PROXY` | - | HTTP 代理地址 |
|
||
| `ADMIN_USERS` | - | 管理员用户ID，逗号分隔 |
|
||
|
||
## 内置命令
|
||
|
||
| 命令 | 说明 | 权限 |
|
||
|------|------|------|
|
||
| `菜单` | 显示所有可用命令 | 所有人 |
|
||
| `启用 <命令名>` | 启用指定命令 | 管理员 |
|
||
| `禁用 <命令名>` | 禁用指定命令 | 管理员 |
|
||
| `时间` | 查询当前时间 | 所有人 |
|
||
|
||
## 插件命令
|
||
|
||
| 命令 | 说明 | 权限 |
|
||
|------|------|------|
|
||
| `生图 <描述>` | 根据描述生成图片 | 所有人 |
|
||
|
||
## 添加新插件
|
||
|
||
### 1. 创建插件文件
|
||
|
||
新建 `plugins/weather/weather.go`：
|
||
|
||
```go
|
||
package weather
|
||
|
||
import (
|
||
"ncatbot-command-server/command"
|
||
)
|
||
|
||
type Plugin struct{}
|
||
|
||
func init() {
|
||
command.RegisterPlugin(&Plugin{})
|
||
}
|
||
|
||
func (p *Plugin) Name() string { return "天气" }
|
||
func (p *Plugin) Description() string { return "查询天气" }
|
||
func (p *Plugin) Usage() string { return "天气 <城市>" }
|
||
func (p *Plugin) Run(req *command.Req) command.Resp {
|
||
return command.Resp{Reply: "今天晴天"}
|
||
}
|
||
```
|
||
|
||
### 2. 注册插件
|
||
|
||
在 `plugins/plugins.go` 中添加导入：
|
||
|
||
```go
|
||
import (
|
||
_ "ncatbot-command-server/plugins/image"
|
||
_ "ncatbot-command-server/plugins/weather" // 新增
|
||
)
|
||
```
|
||
|
||
### Plugin 接口
|
||
|
||
| 接口 | 方法 | 必须实现 |
|
||
|------|------|----------|
|
||
| `Plugin` | `Name()`, `Description()`, `Usage()`, `Run()` | 是 |
|
||
| `PluginWithInit` | 加 `Init()` | 需要初始化时 |
|
||
| `PluginAdmin` | 加 `IsAdminOnly()` | 管理员专用时 |
|
||
|
||
## 请求格式
|
||
|
||
```json
|
||
POST /
|
||
|
||
{
|
||
"command": "生图",
|
||
"content": "一只猫",
|
||
"raw_message": "生图 一只猫",
|
||
"user_id": "123456",
|
||
"group_id": "789",
|
||
"message_id": "abc"
|
||
}
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
文本回复：
|
||
|
||
```json
|
||
{
|
||
"reply": "当前时间是: 2026-05-04 16:00:00"
|
||
}
|
||
```
|
||
|
||
图片回复：
|
||
|
||
```json
|
||
{
|
||
"messages": [
|
||
{
|
||
"type": "image",
|
||
"url": "https://example.com/image.png"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|