QWQLwToo
158 lines
5.2 KiB
Markdown
158 lines
5.2 KiB
Markdown
# YMhut Box 反馈工单服务
|
||
|
||
这是 `server/feedback-mailer` 下的 Go + Gin + SQLite 反馈服务。旧 PHP 入口已移除，线上入口由 Go 服务接管；`config.txt`、`storage/`、`storage/feedback.sqlite` 和历史 `.ymfb` / `.zip` 文件继续保留并兼容读取。
|
||
|
||
## 运行
|
||
|
||
在 `server/feedback-mailer` 目录直接运行：
|
||
|
||
```bash
|
||
go run main.go
|
||
```
|
||
|
||
监听地址以核心配置文件 `config.txt` 的 `listen` 为准：
|
||
|
||
```php
|
||
'listen' => ':8080',
|
||
```
|
||
|
||
服务器部署时也可以显式设置服务根目录：
|
||
|
||
```bash
|
||
export YMHUT_FEEDBACK_HOME=/opt/feedback-mailer
|
||
./feedback-mailer
|
||
```
|
||
|
||
后台入口：
|
||
|
||
```text
|
||
http://127.0.0.1:8080/admin/
|
||
```
|
||
|
||
生产构建与检查：
|
||
|
||
```bash
|
||
npm --prefix admin-web install
|
||
npm --prefix admin-web run build
|
||
go test ./...
|
||
go build .
|
||
```
|
||
|
||
## 配置
|
||
|
||
优先读取当前目录的 `config.txt`，这是线上实际配置文件，部署时不要覆盖。没有 `config.txt` 时才回退读取 `config.json`。
|
||
|
||
关键字段：
|
||
|
||
- `listen`：服务监听地址，例如 `:8080`、`:9090`、`127.0.0.1:8080`。
|
||
- `admin_password_hash` / `admin_password`：后台登录密码，推荐使用 bcrypt hash。
|
||
- `client_signature_key`：旧 WinUI 客户端 HMAC 签名密钥，必须保持一致。
|
||
- `package_encryption_key`：`.ymfb` 反馈包解密密钥，必须保持一致。
|
||
- `storage_dir`：默认 `storage`，保留历史反馈包。
|
||
- `database_path`：默认 `storage/feedback.sqlite`，保留旧 SQLite 数据。
|
||
- `rate_limit`：提交、状态查询、验证码、登录和后台 API 的令牌桶限流。
|
||
- `upload_guard`：zip 文件数量、解压后大小、单文件大小、压缩比、路径穿越校验。
|
||
- `backup.dir` / `backup_dir`：数据库只读备份输出目录，默认 `storage/backups`。
|
||
- `webhooks`：通用 Webhook 通知配置，secret 只用于签名，不进入 URL 或配置健康 API。
|
||
|
||
## 兼容接口
|
||
|
||
旧客户端提交接口保持不变：
|
||
|
||
```text
|
||
POST /
|
||
```
|
||
|
||
继续接收 `payload`、`timestamp`、`nonce`、`packageSha256`、`signature`、`package`，并保留旧错误码。
|
||
|
||
旧状态查询保持不变：
|
||
|
||
```text
|
||
GET /?api=status&code=FB-YYYYMMDD-XXXXXX
|
||
```
|
||
|
||
响应保留旧字段，并兼容增加 `statusDetail`、`category`、`priority`。
|
||
|
||
## 后台能力
|
||
|
||
- 公共首页 `/`：反馈中心正式页和无需登录的状态查询。
|
||
- 后台 `/admin/`：工作台、工单流、状态看板、通知记录、Webhook 集成、运维、配置健康。
|
||
- 10 秒轮询刷新：统计卡片、SVG 图表、工单列表、详情、通知和配置摘要都会重绘。
|
||
- 工单增强：状态、分类、优先级、SLA、指派人、截止时间、标签、评论、解决说明、内部备注、公开回复。
|
||
- 看板操作：按 `new / triaged / investigating / resolved / archived` 分栏，拖动工单即可改状态。
|
||
- 批量处理：多选后批量归类、处理中、解决、归档。
|
||
- 导出：`GET /api/admin/feedbacks/export?format=csv` 导出当前筛选结果，不包含包文件和密钥。
|
||
- 审计日志：登录、工单修改、批量操作、导出、备份、Webhook 测试等都会记录。
|
||
- 数据库备份：后台创建和下载 SQLite 备份，不提供在线删除、VACUUM 或破坏性维护。
|
||
- Webhook：支持 `feedback.created`、`feedback.updated`、`feedback.status_changed`、`feedback.comment_created`、`mail.failed`。
|
||
|
||
Webhook 请求头：
|
||
|
||
```text
|
||
X-YMhut-Event
|
||
X-YMhut-Delivery
|
||
X-YMhut-Signature
|
||
```
|
||
|
||
签名格式为 `sha256=<hex hmac>`。
|
||
|
||
## 数据升级
|
||
|
||
服务启动时会对旧 `feedbacks` 表做非破坏性补列，并创建新表：
|
||
|
||
- `feedback_comments`
|
||
- `feedback_tags`
|
||
- `audit_logs`
|
||
- `webhook_deliveries`
|
||
- `feedback_events`
|
||
|
||
SQLite 默认启用 WAL，并设置 `busy_timeout`。不会删除 `storage/feedback.sqlite`，不会修改历史 `.ymfb`、`.zip` 文件。
|
||
|
||
## 后台 API
|
||
|
||
需要登录 session，写接口需要 CSRF：
|
||
|
||
- `GET /api/admin/overview`
|
||
- `GET /api/admin/config`
|
||
- `GET /api/admin/feedbacks?page=&perPage=&status=&category=&priority=&mail=&q=&assignee=&tag=&sla=&overdue=&sort=`
|
||
- `GET /api/admin/feedbacks/export?format=csv`
|
||
- `GET /api/admin/feedbacks/summary`
|
||
- `GET /api/admin/feedbacks/:code`
|
||
- `PATCH /api/admin/feedbacks/:code`
|
||
- `PATCH /api/admin/feedbacks/bulk`
|
||
- `POST /api/admin/feedbacks/:code/comments`
|
||
- `GET /api/admin/mails?page=&perPage=&status=`
|
||
- `POST /api/admin/mails/test`
|
||
- `GET /api/admin/audit-logs?page=&perPage=&actor=&type=`
|
||
- `GET /api/admin/webhooks/deliveries?page=&perPage=&status=`
|
||
- `POST /api/admin/webhooks/test`
|
||
- `POST /api/admin/backups/database`
|
||
- `GET /api/admin/backups`
|
||
- `GET /api/admin/backups/:name`
|
||
|
||
## 增强依据
|
||
|
||
- OWASP File Upload Cheat Sheet：上传限额、存储隔离、路径和内容校验、防 zip bomb。
|
||
- OWASP REST Security Cheat Sheet：限流、审计、避免敏感信息出现在 URL、统一错误语义。
|
||
- SQLite WAL 与备份文档：读写并发和在线备份思路。
|
||
- Go `golang.org/x/time/rate`：内存令牌桶限流。
|
||
- Gin graceful shutdown 示例：使用 `http.Server.Shutdown()` 优雅停机。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
go test ./...
|
||
go build .
|
||
npm --prefix admin-web run build
|
||
go run main.go
|
||
```
|
||
|
||
启动后建议检查：
|
||
|
||
```text
|
||
http://127.0.0.1:8080/
|
||
http://127.0.0.1:8080/admin/
|
||
http://127.0.0.1:8080/?api=status&code=BAD
|
||
http://127.0.0.1:8080/api/auth/captcha
|
||
```
|