# MC Report — 部署文档

## 环境要求

- Node.js ≥ 18 / npm ≥ 9
- MySQL ≥ 5.7(或 MariaDB ≥ 10.2)

## 快速开始

```bash
npm install
node backend/server.js
# → 浏览器打开 http://localhost:3100
# → 自动跳转安装向导
```

### 安装向导

**第1步:数据库配置**
- MySQL 主机(默认 localhost)
- 端口(默认 3306)
- 用户名 / 密码
- 数据库名(不存在则自动创建)

**第2步:创建服主账号**
- 站点名称、站点地址
- 服主用户名、密码、邮箱

> 安装完成后**无需重启**,页面自动刷新并进入登录。

## 配置文件 `data/config.json`

```json
{
  "db_host": "localhost",
  "db_port": 3306,
  "db_user": "root",
  "db_pass": "",
  "db_name": "mc_report",
  "jwt_secret": "(安装时随机64位)",
  "api_key": "(安装时随机48位)"
}
```

> `data/` 目录不入库(git 忽略),包含 config.json 与上传文件,请做好备份。

## 生产部署

```bash
PORT=3100 CORS_ORIGIN=https://your-domain.com node backend/server.js
```

### PM2

```bash
npm i -g pm2
pm2 start backend/server.js --name mc-report
pm2 save && pm2 startup
```

### Nginx

```nginx
server {
    listen 80;
    server_name mc.example.com;
    client_max_body_size 55m;

    location / {
        proxy_pass http://127.0.0.1:3100;
        include nginx.inc;
    }
}
```

## 升级迁移

服务启动时自动执行幂等迁移(`backend/db.js` 的 `migrateAdditions`),老库无需手工操作:

- `user_identities` 表创建 + 从 `users` 主身份回填(多来源身份)
- `sources` 表创建并预置 `netease`/`skin`(动态来源)
- `api_clients` / `api_sessions` 表创建(外部 API SESSION 鉴权)
- `server_groups.alias`、`tickets/bans.server_name` 列(按子服归属)
- `email_logs` / `system_logs` 表创建(日志)
- `users.source` ENUM → VARCHAR、`game_uid` 可空(去除网易 UID 依赖)

升级后建议重启一次并清浏览器缓存(HTML 中注入的 api_key 会随重装刷新)。

## 邮件配置

后台 → 系统设置 → SMTP 填写。未配置时注册用户自动激活(dev 模式验证码直接显示在前端)。

## Webhook 通知

后台 → 通知配置 → 添加 Webhook URL(Discord/企微/QQ/飞书均可)→ 选择触发事件(工单创建/认领/转交/更新)。

## 日志排查

后台 → 系统日志(owner/admin):

- **邮件日志**:收件人/模板/状态(成功/失败)/错误信息
- **系统日志**:级别/来源(webhook、mailer、server 等)/消息/详情

配合 `pm2 logs mc-report` 可完整定位问题。

## 外部 API(机器人/插件)

后台 → 外部API → 创建客户端(ID 16 位数字 + Secret 32 位随机,secret 仅显示一次)→ `POST /api/external/auth/session` 换取 SESSION → 其余接口带 `Authorization: Bearer <SESSION>`。

接口清单与插件对接示例见 [docs/EXTERNAL-API.md](docs/EXTERNAL-API.md)、[docs/PLUGIN-GUIDE.md](docs/PLUGIN-GUIDE.md)。

## 来源管理

后台 → 来源管理(owner):增删/停用/排序来源(如 网易端/皮肤站/正版/离线),不设默认。已被身份数据使用的来源不能删除,只能停用。

## 数据库

MySQL,安装时自动建表。备份:

```bash
mysqldump -u root -p mc_report > backup.sql
```

## 目录

```text
mc-report/
├── backend/
│   ├── server.js
│   ├── db.js
│   ├── logger.js
│   ├── mailer.js
│   ├── webhook.js
│   ├── middleware/{auth,security,upload}.js
│   └── routes/{auth,tickets,install,external,sources,users,logs,settings,export,polls,features,notifications,captcha,uploads}.js
├── public/           # 前端 SPA
├── docs/             # API / 外部API / 插件指南
├── nginx.inc
├── data/config.json
├── data/uploads/
├── package.json
├── README.md
├── INSTALL.md
└── LICENSE          # AGPLv3
```

## 许可证

本项目采用 **GNU Affero General Public License v3.0(AGPLv3)**,详见 [LICENSE](LICENSE)。

> 使用/修改/分发本项目请遵守 AGPLv3:修改后的源码必须开源,且通过网络提供服务的修改版本需向用户提供源码。