# Star Raid 部署指南

## 运行要求

- **Node.js ≥ 22.5**（使用内置 `node:sqlite`，零 npm 依赖，无需 `npm install`）
- 配置：`star-raid/.env`（**不进 git**，模板见 `.env.example`，复制后按机器修改）；启动时自动加载，真实环境变量优先于 .env
- 数据库文件默认在 **`~/.starraid/starraid.db`（源码目录之外）**，由 `DATA_DIR` 配置

## 启动

```bash
cd star-raid
npm start                 # = node server/server.js（自动读取 .env）
# 或环境变量临时覆盖（优先级高于 .env）
PORT=9000 node server/server.js
```

| 配置项（.env / 环境变量） | 默认 | 说明 |
|---|---|---|
| `PORT` | `8643` | 监听端口 |
| `HOST` | `0.0.0.0` | 监听地址 |
| `DATA_DIR` | `~/.starraid` | **数据库目录（勿放源码树内）**，支持 `~` 开头 |
| `COOKIE_SECURE` | 空 | **HTTPS 部署时必须设为 `1`**（Cookie 加 Secure） |

## 公网部署（nginx + HTTPS 推荐）

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;
    # ssl_certificate / certbot 申请
    location / {
        proxy_pass http://127.0.0.1:8643;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;   # 限流按真实 IP
    }
}
```

启动时 `COOKIE_SECURE=1 PORT=8643 node server/server.js`，用 systemd/supervisor 守护进程。

## 已实现的安全措施

- 密码：scrypt + 每用户随机盐 + 时序安全比较；登陆失败统一报错（不泄露账号是否存在），不存在账号也跑一次哈希防时序探测
- 会话：32 字节随机 token 存服务端 SQLite，HttpOnly + SameSite=Lax，7 天滑动续期，可吊销
- SQL 注入：全部 prepared statement；图鉴 key 服务端白名单（`server/api.js` 的 `CODEX_KEYS`，**新增装备时必须同步**）
- 输入：用户名/邮箱/密码白名单校验；请求体 ≤16KB；POST 强制 `application/json`（配合 SameSite 防 CSRF）
- 限流：注册 10 次/5 分钟/IP，登陆 20 次/5 分钟/IP，成绩上报 20 次/5 分钟/账号
- 静态资源白名单：只放行 `/`、`/css/`、`/js/`（`server/`、`data/`、`demo/` 不可访问），防目录穿越
- 安全头：CSP / X-Frame-Options / X-Content-Type-Options / Referrer-Policy

## v1 边界（明确不做）

- 邮箱仅作唯一标识，**无验证邮件、无找回密码**（需 SMTP 服务，留 v2）
- **反作弊仅为基础校验**（数值范围/限流）：纯客户端游戏无法杜绝作弊，有志者改内存照样能伪造高分。如需严肃竞技，要加服务端回放校验（大工程）
- 星币/机体/永久强化/本地纪录已上服务端（`POST /api/state`，`player_state` 表，2026-08-06）：登陆时服务端存档整体替换本地；最后登录的设备覆盖云端（无冲突合并）；音乐/音效开关等设置仍存 localStorage 不同步
- 排行榜 = 全服单榜，无分页/赛季

## 数据维护

- 数据库位置：`DATA_DIR`（默认 `~/.starraid`）下的 `starraid.db` + `-wal`/`-shm`
- **WAL 模式警告：备份/迁移前必须先合并日志**——停服后拷贝，或执行 `PRAGMA wal_checkpoint(TRUNCATE);` 再拷。直接拷主库文件会丢数据（2026-08-06 已踩坑，测试数据全灭）
- 重置排行榜：停服后删除 `DATA_DIR` 下文件，重启自动重建空库