YMhut-box-C-/server/feedback-mailer/README.md

YMhut Box 反馈工单服务

这是 server/feedback-mailer 下的 Go + Gin + SQLite 反馈服务。旧 PHP 入口已移除，线上入口由 Go 服务接管；config.txt、storage/、storage/feedback.sqlite 和历史 .ymfb / .zip 文件继续保留并兼容读取。

运行

在 server/feedback-mailer 目录直接运行：

go run main.go

监听地址以核心配置文件 config.txt 的 listen 为准：

'listen' => ':8080',

服务器部署时也可以显式设置服务根目录：

export YMHUT_FEEDBACK_HOME=/opt/feedback-mailer
./feedback-mailer

后台入口：

http://127.0.0.1:8080/admin/

生产构建与检查：

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。

兼容接口

旧客户端提交接口保持不变：

POST /

继续接收 payload、timestamp、nonce、packageSha256、signature、package，并保留旧错误码。

旧状态查询保持不变：

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 请求头：

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() 优雅停机。

验证

go test ./...
go build .
npm --prefix admin-web run build
go run main.go

启动后建议检查：

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