134 lines
3.7 KiB
Markdown
134 lines
3.7 KiB
Markdown
# 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 域名确定后实现。
|