认证与安全
This content is not available in your language yet.
SRA-server 提供基于访问令牌的鉴权,默认不启用。令牌只保护 /api/**,
/mcp、/openapi 与 WebUI 静态资源不受保护。
通过环境变量或 SRAServer/server.toml 设置 access_token:
# Windows PowerShell$env:SRA_ACCESS_TOKEN = "change-me"
# Linux / macOSexport SRA_ACCESS_TOKEN="change-me"access_token = "change-me"令牌为空或只含空白时不启用鉴权,所有请求直接放行。临时试一下可以这样启动:
SRA_ACCESS_TOKEN=change-me sra serve # Linux / macOS$env:SRA_ACCESS_TOKEN = "change-me"; sra serve # Windows PowerShell令牌是逐字节比较的普通字符串,请使用足够长的随机串,并通过反向代理启用 HTTPS, 避免令牌在传输中被窃听。
两种方式,请求头优先于查询参数:
请求头(推荐)
Section titled “请求头(推荐)”X-Access-Token: change-mecurl -H "X-Access-Token: change-me" http://localhost:5073/api/task/status适用于无法自定义请求头的场景(例如 EventSource 发起的 SSE 日志流):
GET /api/backend/logs/stream?access_token=change-mecurl "http://localhost:5073/api/backend/logs/stream?access_token=change-me"| 路径 | 是否需要令牌 |
|---|---|
/api 及其子路径 |
是 |
POST /api/auth |
否(校验端点本身) |
GET /api/app/background |
否(登录页背景图) |
/mcp |
否(在 /api 之外,且访客模式下不挂载) |
/openapi、/openapi/v1.json |
否 |
| WebUI 静态资源 | 否 |
判定只看路径前缀:只有 /api 本身或 /api/... 才鉴权,/apifoo 这类路径不会被拦截。
未通过校验时返回 HTTP 401 与统一响应体:
{ "success": false, "message": "unauthorized", "data": null }POST /api/auth 无需认证,可用于验证令牌是否正确:
curl -X POST http://localhost:5073/api/auth \ -H "Content-Type: application/json" \ -d '{"token": "change-me"}'| 场景 | HTTP | 响应 |
|---|---|---|
| 令牌匹配 | 200 | {"success": true, "message": "authorized"} |
| 令牌不匹配 | 401 | {"success": false, "message": "unauthorized"} |
| 未配置令牌 | 200 | {"success": true, "message": "No access token configured"} |
访客模式(SRA_VISITOR_MODE=true / visitor_mode = true)适合公开展示:
- 不挂载
/mcp; - 绝大多数写操作不会真正执行,但仍返回成功,避免暴露内部状态:
POST /api/task/run、/api/task/single返回"Task started",但不会运行任务;- 配置的新增/修改/删除、设置修改、扩展运行/停止/重载均为空操作;
POST /api/backend/restart返回成功但不生效;- 例外:
POST /api/backend/stop仍然有效,会停止任务并让服务退出;
GET /api/backend/screenshot返回空的 JPEG,不暴露游戏画面;- 读取类接口(状态、配置列表、设置、扩展列表等)仍然可用。
访客模式不是鉴权机制,写接口返回的 success=true 具有误导性。
需要限制访问时请同时启用访问令牌。
公开部署建议
Section titled “公开部署建议”.NET版本的appsettings.json与SRA-server.exe已不再使用,配置一律通过环境变量或server.toml;- 反向代理只放行需要的路径,例如仅暴露
/(WebUI)与/api,屏蔽/mcp与/openapi; - 默认监听
127.0.0.1,只有显式使用--host或SRA_HOST=0.0.0.0才会对外开放; - 未启用认证时,任何能访问端口的人都可运行任务、修改配置、截取画面并操作游戏, 详见 Docker 部署 中的暴露公网说明。
