270 lines
11 KiB
Markdown
270 lines
11 KiB
Markdown
# 服主配置指南
|
||
|
||
本文面向部署 `bd2server` 的服主，不面向普通玩家。
|
||
|
||
此文为极其诡异不说人话的 GPT 系列模型编写，所以如果你看不懂，那么请丢给 AI。
|
||
|
||
为避免混淆，本文统一使用以下名称：
|
||
|
||
- `provider access token`、`provider ID token`：Discord/Google 在 OAuth/OIDC 流程中返回的凭据，仅由服务端临时使用。
|
||
- `game access token`、`game refresh credential`：`bd2server` 自己签发、供玩家客户端访问本服使用的凭据。
|
||
|
||
除非明确写出 `provider`，下文提到的 access token 或 refresh credential 都指 `bd2server` 自己签发的 game credential。
|
||
|
||
客户端会受到配置结果影响，例如显示哪些按钮、登录能否成功，但客户端不保存或管理 `client_secret`、master key。
|
||
|
||
也就是说，即使你服务器上什么都有，那他们的客户端 `GET /auth/config` 只能看到：
|
||
|
||
```json
|
||
{
|
||
"mode": "oauth",
|
||
"providers": ["discord", "google"]
|
||
}
|
||
```
|
||
|
||
玩家点击第三方登录后，服务端会为本次登录生成一次性随机 `state`、PKCE verifier/challenge，以及 Google OIDC `nonce`。Provider callback 必须匹配对应的短期 login transaction；`state`、授权码和登录事务不能跨事务复用。服主不需要手工生成或配置这些值。
|
||
|
||
## 1. 准备公网地址
|
||
|
||
联机服务器需要一个长期稳定、玩家和 provider 都能访问的 HTTPS origin（当然，我们都自部署服务器了，公网地址肯定是有的），例如：
|
||
|
||
```text
|
||
https://bd2.example.com
|
||
```
|
||
|
||
要求：
|
||
|
||
- `public_url` 只能包含 scheme、主机和可选端口，不能带路径、查询参数、片段或用户信息。
|
||
- **bd2server 自身要求**公网 `public_url` 使用 HTTPS；只有 `localhost`、`127.0.0.1` 或 `::1` 开发环境允许 HTTP。Provider 还可能施加额外的 redirect URI 限制，最终 URI 也必须通过 Discord/Google 后台的校验。
|
||
- 反向代理或内网穿透必须把 `/auth/`、`/game/` 和 `/assets/` 全部转发到我们启动的 `bd2server`。
|
||
- 不要让代理缓存 `/auth/` 响应。
|
||
- 域名变化后，必须同时修改 `authentication.json` 和 provider 后台的 redirect URI，然后重启服务端，并告知玩家。
|
||
|
||
固定回调地址为：
|
||
|
||
```text
|
||
Discord: <public_url>/auth/discord/callback
|
||
Google: <public_url>/auth/google/callback
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
https://bd2.example.com/auth/discord/callback
|
||
https://bd2.example.com/auth/google/callback
|
||
```
|
||
|
||
## 2. 创建 Discord OAuth 应用
|
||
|
||
1. 登录 <https://discord.com/developers/applications>。
|
||
2. 选择 **New App**，为自己的服务器创建一个应用。
|
||
3. 在应用的 **OAuth2** 页面复制 **Client ID**。
|
||
4. 创建应用后立即安全保存 **Client Secret**。如果后台已不显示 secret，再使用 Discord 提供的重置/轮换功能生成新 secret，并同步更新服务端环境变量。不要为了“查看”而无意义地重置仍在使用的 secret。
|
||
5. 在 **Redirects** 中添加：
|
||
|
||
```text
|
||
https://bd2.example.com/auth/discord/callback
|
||
```
|
||
|
||
6. 保存设置。
|
||
|
||
若重置 Discord client secret，旧 secret 会立即失效；更新服务器环境变量并重启即可，玩家客户端不需要改变。Authorization Code 流程使用的一次性 `state` 和 PKCE 由 `bd2server` 自动生成并在 callback 时校验。
|
||
|
||
## 3. 创建 Google OAuth 应用
|
||
|
||
Google 当前主要在 **Google Auth Platform → Branding / Audience / Data Access / Clients** 中管理 OAuth。控制台名称以后可能调整，但需要完成的对象不变：配置应用展示与受众，并创建一个 **Web application** 类型的 OAuth client。
|
||
|
||
1. 登录 <https://console.cloud.google.com/> 并选择或创建项目。
|
||
2. 在 **Branding** 中配置应用名称、支持邮箱等公开信息。
|
||
3. 在 **Audience** 中选择实际目标受众并确认 Publishing status：
|
||
- **测试阶段**：保持 Testing，并把实际参加登录测试的 Google 账号加入 Test users。未列入的玩家会被 Google 拒绝。
|
||
- **向玩家开放前**：检查 Audience、Publishing status 和 Google 显示的发布要求，并按实际受众切换到 In production。
|
||
4. 在 **Data Access** 中核对 scope。`bd2server` 当前只申请最小的 `openid`，不申请 `profile` 或邮箱 scope。
|
||
5. 在 **Clients** 中选择 **Create Client**，应用类型选择 **Web application**。不要创建 Desktop application 类型的 client：浏览器回调落在服务端 HTTPS endpoint，需要 Web application client。
|
||
6. 在 **Authorized redirect URIs** 中添加：
|
||
|
||
```text
|
||
https://bd2.example.com/auth/google/callback
|
||
```
|
||
|
||
7. 创建后立即安全保存 Client ID 和 Client Secret。如果 Google 后台不再允许查看或下载原 secret，就按后台提供的轮换流程创建新 secret，并同步更新服务端环境变量。
|
||
|
||
## 4. 生成并保存 master key
|
||
|
||
每台服务器生成一次 32-byte 随机 master key。
|
||
|
||
Windows（PowerShell 7）：
|
||
|
||
```powershell
|
||
$keyBytes = [byte[]]::new(32)
|
||
$rng = [Security.Cryptography.RandomNumberGenerator]::Create()
|
||
try {
|
||
$rng.GetBytes($keyBytes)
|
||
[Convert]::ToBase64String($keyBytes)
|
||
} finally {
|
||
$rng.Dispose()
|
||
[Array]::Clear($keyBytes, 0, $keyBytes.Length)
|
||
}
|
||
```
|
||
|
||
macOS/Linux（Bash 或 Zsh）：
|
||
|
||
```bash
|
||
master_key="$(openssl rand -base64 32)"
|
||
printf '%s\n' "$master_key"
|
||
unset master_key
|
||
```
|
||
|
||
把输出保存进密码管理器或服务部署系统的 secret store。不要提交到 Git，也不要写进 `authentication.json`。
|
||
|
||
master key 必须长期稳定：
|
||
|
||
- 重启服务端时继续使用同一个值。
|
||
- 备份 `auth.db` 时也要单独安全备份 master key。
|
||
- master key 会派生两类用途隔离密钥：HMAC 密钥用于 provider identity、game token、登录事务 secret、OAuth `state` 和客户端地址的稳定索引；AES-256-GCM 密钥用于 PKCE verifier、OIDC `nonce` 和待领取登录结果。
|
||
- 丢失或随意更换 master key 后，已有 HMAC 索引无法再匹配，已有 AES-GCM 密文也无法解密；现有 `auth.db` 认证状态不能继续使用。
|
||
- 不要在两台互不信任的服务器之间共用 master key。
|
||
|
||
## 5. 编辑服务器配置
|
||
|
||
首次运行时会在 `bd2server` 可执行文件旁生成 `local` 模式的默认配置。开发入口使用 `.build/config/authentication.json`；Docker 镜像默认使用 `/app/data/config/authentication.json`。启用 OAuth 前编辑生成的文件并配置环境变量，然后重启。Discord 和 Google 都启用时：
|
||
|
||
```json
|
||
{
|
||
"mode": "oauth",
|
||
"public_url": "https://bd2.example.com",
|
||
"master_key_env": "BD2_AUTH_MASTER_KEY",
|
||
"providers": {
|
||
"discord": {
|
||
"client_id": "123456789012345678",
|
||
"client_secret_env": "BD2_DISCORD_CLIENT_SECRET"
|
||
},
|
||
"google": {
|
||
"client_id": "example.apps.googleusercontent.com",
|
||
"client_secret_env": "BD2_GOOGLE_CLIENT_SECRET"
|
||
}
|
||
},
|
||
"session": {
|
||
"access_ttl": "15m",
|
||
"refresh_ttl": "720h",
|
||
"device_transaction_ttl": "10m"
|
||
}
|
||
}
|
||
```
|
||
|
||
配置字段 `device_transaction_ttl` 以及服务端日志中可能出现的 login transaction，指 `bd2server` 自己用于“游戏客户端发起登录 → 浏览器完成 Authorization Code → 游戏客户端领取结果”的短期交接机制。它不是 Discord 或 Google 的 OAuth Device Authorization Grant。
|
||
|
||
只启用一个 provider 时，删除另一个 provider 对象即可。`providers` 是对象映射，不是字符串数组。
|
||
|
||
JSON 中可以保存 `client_id`，因为它不是秘密；只能保存 secret 所在环境变量的名称，不能保存 secret 实值。
|
||
|
||
## 6. 向服务端进程注入 secret
|
||
|
||
临时测试时，在启动 `bd2server` 的同一个 shell 中设置。
|
||
|
||
Windows（PowerShell 7）：
|
||
|
||
```powershell
|
||
$env:BD2_AUTH_MASTER_KEY = '<Base64 32-byte master key>'
|
||
$env:BD2_DISCORD_CLIENT_SECRET = '<Discord client secret>'
|
||
$env:BD2_GOOGLE_CLIENT_SECRET = '<Google client secret>'
|
||
|
||
.\bd2server.exe serve
|
||
```
|
||
|
||
macOS/Linux（Bash 或 Zsh）：
|
||
|
||
```bash
|
||
export BD2_AUTH_MASTER_KEY='<Base64 32-byte master key>'
|
||
export BD2_DISCORD_CLIENT_SECRET='<Discord client secret>'
|
||
export BD2_GOOGLE_CLIENT_SECRET='<Google client secret>'
|
||
|
||
./bd2server serve
|
||
```
|
||
|
||
如果只启用 Discord，就不需要设置 Google secret；反之亦然。服务端在 OAuth 配置或任何必需环境变量缺失时会拒绝启动。
|
||
|
||
## 7. 启动后检查
|
||
|
||
先检查服务健康。
|
||
|
||
Windows（PowerShell 7）：
|
||
|
||
```powershell
|
||
$publicUrl = 'https://bd2.example.com'
|
||
(Invoke-WebRequest -Uri "$publicUrl/healthz").Content
|
||
```
|
||
|
||
macOS/Linux（Bash 或 Zsh）：
|
||
|
||
```bash
|
||
PUBLIC_URL='https://bd2.example.com'
|
||
curl --fail --silent --show-error "$PUBLIC_URL/healthz"
|
||
```
|
||
|
||
预期输出：
|
||
|
||
```text
|
||
ok
|
||
```
|
||
|
||
再检查公开认证策略。
|
||
|
||
Windows（PowerShell 7）：
|
||
|
||
```powershell
|
||
Invoke-RestMethod -Uri "$publicUrl/auth/config" | ConvertTo-Json
|
||
```
|
||
|
||
macOS/Linux（Bash 或 Zsh）：
|
||
|
||
```bash
|
||
curl --fail --silent --show-error "$PUBLIC_URL/auth/config"
|
||
```
|
||
|
||
正常响应只应包含公开认证策略，例如 `mode` 和 provider 名称：
|
||
|
||
```json
|
||
{
|
||
"mode": "oauth",
|
||
"providers": ["discord", "google"]
|
||
}
|
||
```
|
||
|
||
最后再启动玩家客户端。首次进入应显示服主启用的 Discord/Google 按钮；浏览器地址应属于 Discord/Google，回调应返回配置的 `public_url`。
|
||
|
||
## 9. 常见问题
|
||
|
||
### 客户端需要填写 client ID 或 secret 吗？
|
||
|
||
不需要。客户端只读取服务端公开的 provider 列表。Client ID 由服务端构造 OAuth 授权 URL 时使用；client secret 只参与服务端与 provider token endpoint 之间的通信。浏览器中的 provider 授权 URL 会包含 client ID，这是正常行为，因为 client ID 本来就不是 secret。
|
||
|
||
### client ID 写错会破坏玩家存档吗？
|
||
|
||
这些配置错误通常不会修改 `state.db`，但可能导致认证失败、callback 无法完成、请求被送到错误 host，或 login transaction 超时。修正配置并重启服务端即可；客户端不会因此得到 client secret。
|
||
|
||
### 可以让所有服主共用项目作者的一组 client ID/secret 吗？
|
||
|
||
不建议，也不应分发共享 client secret。每位服主应创建自己的 OAuth 应用，独立控制回调域名、配额、停用和审计。共享应用会把所有服务器的信任、限流和泄漏风险绑在一起。
|
||
|
||
### 换域名需要重新编译客户端插件吗？
|
||
|
||
登录插件本身不需要重新编译，但客户端最初连接的服务端入口、`authentication.json` 的 `public_url`、反向代理以及 provider redirect URI 必须全部指向新地址并保持一致。
|
||
|
||
### 可以把服务直接暴露在公网 HTTP 上吗？
|
||
|
||
不可以。公网 OAuth 会传输一次性 device secret、登录结果和游戏凭据，必须由 HTTPS 保护。只有同机 loopback 开发测试允许 HTTP。
|
||
|
||
### 如何撤销当前客户端自动登录？
|
||
|
||
客户端退出账号时会删除当前服务器 origin 对应的安全 refresh credential。服主还可以调用服务端 session revoke 流程；不要通过删除 `state.db` 来“清登录”，玩家存档与认证数据是分开的。
|
||
|
||
### 如何重置服务器 owner？
|
||
|
||
这属于破坏性管理操作。当前没有公开的 owner 重置 API，不要手工改 SQLite。应先停止服务、完整备份并校验 `state.db`、`auth.db` 和 master key，再使用未来提供的受控管理工具。删除 `state.db` 会删除玩家存档，不是正确的认证重置方法。
|
||
|
||
## 10. 官方教程
|
||
|
||
- Discord OAuth2：<https://discord.com/developers/docs/topics/oauth2>
|
||
- Google OAuth 2.0 for Web Server Applications：<https://developers.google.com/identity/protocols/oauth2/web-server>
|