Initial commit

2026-08-24 17:27:41 +08:00
commit 5ff80caf7e
45 changed files with 11485 additions and 0 deletions
@@ -0,0 +1,133 @@
+# 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
+
+## 架构
+
+```text
+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
+
+```sh
+cp .env.example .env
+```
+
+编辑 `.env`：
+
+- 将 `FEEDBACK_DOMAIN` 改为真实域名
+- 用至少 32 字节的随机值替换 `APP_SECRET`
+
+可用以下方式生成 secret：
+
+```sh
+APP_SECRET="$(openssl rand -hex 32)"
+sed -i "s|^APP_SECRET=.*|APP_SECRET=${APP_SECRET}|" .env
+unset APP_SECRET
+chmod 600 .env
+```
+
+构建镜像并创建首个管理员：
+
+```sh
+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
+```
+
+启动服务：
+
+```sh
+docker compose up -d
+docker compose ps
+curl "https://feedback.example.com/health"
+```
+
+将示例域名替换为 `.env` 中的真实域名。管理后台位于
+`https://你的域名/admin/`。
+
+> 管理员创建命令也用于密码重置。重置后，该管理员的所有既有会话会立即
+> 失效。不要把密码写入 `.env`、命令参数或 Git。
+
+## 本地开发
+
+要求 Node.js 24 或更新版本。
+
+```sh
+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`：
+
+```sh
+npm run dev
+# 另一个终端
+npm run dev:admin
+```
+
+## 文档
+
+- [公共 API 契约](docs/api.md)
+- [部署、升级、备份与恢复](docs/operations.md)
+- [数据与隐私边界](docs/privacy.md)
+- [GoodBuddy 接入边界](docs/goodbuddy-integration.md)
+
+## 当前边界
+
+- 这是单机部署方案，不提供多节点 SQLite 共享写入。
+- 反馈和附件默认持续保留，由部署方制定并执行保留策略。
+- 管理后台不对公网提供注册入口，管理员只能通过主机命令创建或重置。
+- GoodBuddy 桌面端接入将在生产 API 域名确定后实现。