# Xuqm Symbolicator

BugCollect 的独立符号化服务，提供 React Native、Electron、Vue、Android、iOS 和 Flutter
堆栈处理入口。服务只负责符号化，不保存上传内容。

## 运行基线

- 生产容器：Node.js 24 LTS
- 本地开发：Node.js 22.22 及以上受支持版本
- 安装：`npm ci`
- 构建：`npm run build`
- 测试：`npm test`
- 完整检查：`npm run check`

## HTTP 契约

- `GET /health`：返回服务状态。
- `POST /api/symbolicate`：保持现有 JSON 请求与 JSON 响应结构。
- 配置 `SYMBOLICATOR_API_KEY` 后，请求必须通过 `x-api-key` 请求头认证；未配置时保持
  既有开发模式行为。
- 请求体最大 105 MiB。业务字段仍分别限制堆栈 100 KB、Sourcemap 50 MB 和
  ProGuard/R8 mapping 100 MB，超限请求不会进入解析器。

服务不提供 multipart 文件上传接口。`multer` 仅保留为现有依赖契约并升级至安全版本，
不得在未定义文件数量、单文件大小、总大小和临时文件清理规则前直接启用。

## 容器

```bash
docker build -t xuqm-symbolicator:local .
docker run --rm -p 3000:3000 xuqm-symbolicator:local
```

镜像使用锁文件安装、多阶段构建和非 root 用户运行。健康检查访问容器内
`http://127.0.0.1:3000/health`。

当前 Linux 容器不内置 macOS `atos` 或 Flutter SDK。因此 iOS/Flutter 请求接口仍保留，
但对应外部工具必须由实际部署环境提供；不能用 TypeScript 构建结果替代这两类运行验证。

## 安全边界

- 日志不得输出 API Key、请求体、Sourcemap、mapping、堆栈内容或宿主文件路径。
- 不得把来自请求的路径或命令参数拼接进 shell；现有外部工具调用统一使用参数数组。
- 依赖变更必须同步提交 `package-lock.json` 并使用 `npm ci` 验证。