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 改为真实域名
设置 INITIAL_ADMIN_EMAIL 和 INITIAL_ADMIN_PASSWORD
可按需设置 INITIAL_ADMIN_NAME

APP_SECRET 可以留空，应用会在数据目录生成并持久化随机 secret。

启动服务：

docker compose up -d
docker compose ps
curl "https://feedback.example.com/health"

首次启动只在数据库没有管理员时根据 .env 创建初始管理员，不会在后续重启时重置密码。创建完成后建议从 .env 删除 INITIAL_ADMIN_PASSWORD。

将示例域名替换为 .env 中的真实域名。管理后台位于 https://你的域名/admin/。

admin:create 命令仍可用于创建或重置其他管理员。重置后，该管理员的所有既有会话会立即失效。

本地开发

要求 Node.js 24 或更新版本。

cp .env.example .env
# 示例配置可直接启动；对外部署前必须修改初始管理员凭据
npm ci
npm run typecheck
npm test
npm run lint
npm run build

Node 后端和管理员 CLI 会自动读取项目根目录的 .env。已由 shell、PM2 或系统服务注入的同名环境变量优先，不会被文件中的值覆盖。可通过 ENV_FILE=/path/to/file 指定其他配置文件。

后端默认监听 127.0.0.1:3000，管理后台 Vite 服务默认监听 127.0.0.1:5174 并代理 /api：

npm run dev
# 另一个终端
npm run dev:admin

PM2 运行

没有 Docker 时可使用 PM2 直接管理构建后的 Node 进程：

npm install --global pm2
cp .env.example .env
# 示例配置可直接启动；生产环境必须先修改初始管理员凭据
npm run pm2:start
pm2 save

初始管理员仅在数据库为空时创建。确认可以登录后，建议删除 .env 中的 INITIAL_ADMIN_PASSWORD，再执行 npm run pm2:reload。未设置 APP_SECRET 时，应用会把自动生成的 secret 保存到 DATA_DIRECTORY/.app-secret。

更新代码后运行 npm run pm2:reload，查看日志使用 pm2 logs product-issue。默认访问地址为 http://127.0.0.1:3000/admin/。

文档

当前边界

这是单机部署方案，不提供多节点 SQLite 共享写入。
反馈和附件默认持续保留，由部署方制定并执行保留策略。
管理后台不对公网提供注册入口，管理员只能通过主机命令创建或重置。
GoodBuddy 桌面端接入将在生产 API 域名确定后实现。

4.3 KiB Raw Blame History Unescape Escape