143 lines
4.3 KiB
Markdown
143 lines
4.3 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` 改为真实域名
|
||
- 设置 `INITIAL_ADMIN_EMAIL` 和 `INITIAL_ADMIN_PASSWORD`
|
||
- 可按需设置 `INITIAL_ADMIN_NAME`
|
||
|
||
`APP_SECRET` 可以留空，应用会在数据目录生成并持久化随机 secret。
|
||
|
||
启动服务：
|
||
|
||
```sh
|
||
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 或更新版本。
|
||
|
||
```sh
|
||
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`：
|
||
|
||
```sh
|
||
npm run dev
|
||
# 另一个终端
|
||
npm run dev:admin
|
||
```
|
||
|
||
## PM2 运行
|
||
|
||
没有 Docker 时可使用 PM2 直接管理构建后的 Node 进程：
|
||
|
||
```sh
|
||
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/`。
|
||
|
||
## 文档
|
||
|
||
- [公共 API 契约](docs/api.md)
|
||
- [部署、升级、备份与恢复](docs/operations.md)
|
||
- [数据与隐私边界](docs/privacy.md)
|
||
- [GoodBuddy 接入边界](docs/goodbuddy-integration.md)
|
||
|
||
## 当前边界
|
||
|
||
- 这是单机部署方案，不提供多节点 SQLite 共享写入。
|
||
- 反馈和附件默认持续保留，由部署方制定并执行保留策略。
|
||
- 管理后台不对公网提供注册入口，管理员只能通过主机命令创建或重置。
|
||
- GoodBuddy 桌面端接入将在生产 API 域名确定后实现。
|