3.7 KiB
3.7 KiB
MesaLogo Product Issue
MesaLogo Product Issue 是一个可独立部署的多产品反馈平台。GoodBuddy 是默认接入的第一个产品，后续产品可在管理后台创建并独立筛选。
平台将公开提交 API、内部管理后台、SQLite 数据库和私有截图存储放在 同一套单机部署中，不依赖 GitHub Issue 作为核心数据源。
已实现能力
- 版本化公共反馈 API，支持问题、建议、体验和其他反馈
- 可选联系邮箱、客户端环境信息和一张截图
- 按产品和客户端请求 ID 幂等提交
- 默认
goodbuddy产品，以及后台中的多产品创建和启停 - 中文管理后台，包含统计、搜索、筛选、分页和反馈详情
待处理 → 已分诊 → 处理中 → 已解决 → 已关闭状态流转- 仅管理员可见的截图和内部备注
- SQLite WAL 持久化，截图使用独立私有目录
- scrypt 管理员密码、HttpOnly 会话 Cookie 和 CSRF 校验
- IP 与安装实例双层限流
- PNG/JPEG/WebP 解码校验、自动旋转、PNG 重编码和元数据清理
- Docker Compose + Caddy 单机部署及自动 HTTPS
架构
GoodBuddy / 其他产品
|
| HTTPS POST /api/v1/feedback
v
Caddy
|
v
Fastify + React 管理后台
|
+---- SQLite (反馈、产品、管理员、会话、备注)
|
+---- 私有 attachments/ (标准化 PNG)
管理后台与 API 同源部署。只有 Caddy 暴露 80/443 端口，应用容器不直接 发布端口。
快速部署
要求：
- 一台安装了 Docker Engine 和 Docker Compose v2 的 Linux 主机
- 一个已将 A/AAAA 记录指向该主机的域名
- 公网可访问的 TCP 80、TCP 443 和 UDP 443
cp .env.example .env
编辑 .env：
- 将
FEEDBACK_DOMAIN改为真实域名 - 用至少 32 字节的随机值替换
APP_SECRET
可用以下方式生成 secret：
APP_SECRET="$(openssl rand -hex 32)"
sed -i "s|^APP_SECRET=.*|APP_SECRET=${APP_SECRET}|" .env
unset APP_SECRET
chmod 600 .env
构建镜像并创建首个管理员：
docker compose build
read -rsp "Administrator password: " PRODUCT_ISSUE_ADMIN_PASSWORD
echo
export PRODUCT_ISSUE_ADMIN_PASSWORD
docker compose run --rm \
-e PRODUCT_ISSUE_ADMIN_PASSWORD \
app node dist/server/server/cli/create-admin.js \
--email admin@example.com \
--name "MesaLogo Admin"
unset PRODUCT_ISSUE_ADMIN_PASSWORD
启动服务：
docker compose up -d
docker compose ps
curl "https://feedback.example.com/health"
将示例域名替换为 .env 中的真实域名。管理后台位于
https://你的域名/admin/。
管理员创建命令也用于密码重置。重置后，该管理员的所有既有会话会立即 失效。不要把密码写入
.env、命令参数或 Git。
本地开发
要求 Node.js 24 或更新版本。
npm ci
npm run typecheck
npm test
npm run lint
npm run build
开发服务器需要通过进程环境提供 APP_SECRET 和其他配置。后端默认监听
127.0.0.1:3000，管理后台 Vite 服务默认监听 127.0.0.1:5174 并代理
/api：
npm run dev
# 另一个终端
npm run dev:admin
文档
当前边界
- 这是单机部署方案，不提供多节点 SQLite 共享写入。
- 反馈和附件默认持续保留，由部署方制定并执行保留策略。
- 管理后台不对公网提供注册入口，管理员只能通过主机命令创建或重置。
- GoodBuddy 桌面端接入将在生产 API 域名确定后实现。