认证和安全

相关源文件

• modules/api/api.py
• modules/api/models.py

本文档提供了 Stable Diffusion Web UI API 的身份验证和安全功能的全面指南。它涵盖了 HTTP 基本身份验证机制、URL 验证、请求过滤、TLS/SSL 支持以及保护 API 部署的最佳实践。

有关 API 端点和用法的更多信息，请参阅 API 参考和 API 端点。

认证系统

Stable Diffusion Web UI API 支持 HTTP 基本身份验证，以防止未经授权的用户访问 API。

启用身份验证

身份验证默认禁用，必须在启动应用程序时使用 --api-auth 命令行参数显式启用。

python launch.py --api --api-auth="username:password"

可以通过逗号分隔来指定多个凭据

python launch.py --api --api-auth="user1:pass1,user2:pass2"

来源： modules/api/api.py201-205

身份验证流程

启用身份验证后，所有 API 端点都需要在 HTTP 请求头中提供有效的凭据。

来源： modules/api/api.py274-284

实现细节

身份验证通过 FastAPI 的依赖注入系统和 HTTP Basic 安全方案实现

1. 在 API 初始化期间，凭据字典是根据 --api-auth 参数创建的
2. 启用身份验证后，API 路由将与身份验证依赖项一起注册
3. auth() 方法使用 compare_digest 进行安全的字符串比较来验证用户凭据
4. 身份验证失败会返回 401 状态码，并带有 WWW-Authenticate: Basic 头部

来源： modules/api/api.py279-284

URL 安全

API 实施 URL 验证，以防止因允许任意 URL 请求而带来的安全风险。

URL 验证

URL 验证可防止通过外部 URL 请求未经授权访问本地资源。

来源： modules/api/api.py58-74 modules/api/api.py77-99

API URL 安全功能

API 实现了多项 URL 处理安全功能

1. 外部请求控制：API 可通过 api_enable_requests 选项禁用所有外部请求
2. 本地请求保护：启用 api_forbid_local_requests 后，将阻止对本地资源的请求
3. URL 验证：verify_url 函数分析 URL，以确定它们是指向本地还是全局资源
4. 自定义用户代理：API 可通过 api_useragent 选项为外部请求使用指定的用户代理

来源： modules/api/api.py58-83

API 请求日志

API 包含一个全面的日志系统，可以启用以跟踪所有 API 请求。

日志格式

启用后，API 日志将包含：

• 时间戳
• HTTP 状态码
• 协议/版本
• HTTP 方法
• 端点路径
• 客户端 IP 地址
• 请求时长

日志条目示例

API 2023-05-01 12:34:56.789 200 http/1.1 POST /sdapi/v1/txt2img 192.168.1.100 0.4567

要启用日志记录，请使用 --api-log 命令行参数

python launch.py --api --api-log

来源： modules/api/api.py147-165

错误处理与报告

API 实现了健壮的错误处理，以便在发生问题时提供清晰的反馈。

错误响应格式

API 错误以标准 JSON 格式返回

API 根据错误类型使用不同的错误处理策略

• HTTP 异常返回状态码和错误详情
• 当可进行详细打印时，意外异常包含详细的错误信息
• 所有异常都会被记录以供故障排除

来源： modules/api/api.py167-196

TLS/SSL 支持

API 支持 TLS/SSL 加密以实现安全通信。

启用 TLS/SSL

要启用 TLS/SSL，请在启动应用程序时提供证书和密钥文件

python launch.py --api --tls-keyfile=key.pem --tls-certfile=cert.pem

来源： modules/api/api.py905-916

服务器控制安全

API 包含用于控制服务器的端点，出于安全原因，这些端点默认禁用。

服务器控制端点

以下服务器控制端点仅在明确启用时可用

端点	功能	描述
/sdapi/v1/server-kill	kill_webui	完全终止应用程序
/sdapi/v1/server-restart	restart_webui	重启应用程序
/sdapi/v1/server-stop	stop_webui	优雅地停止服务器

要启用这些端点，请使用 --api-server-stop 命令行标志

python launch.py --api --api-server-stop

来源： modules/api/api.py248-252 modules/api/api.py917-927

API 身份验证集成

下图展示了身份验证如何集成到 API 路由注册过程中

来源： modules/api/api.py199-210 modules/api/api.py274-284

安全最佳实践

在部署 Stable Diffusion Web UI API 时，请考虑以下安全最佳实践：

1. 始终启用身份验证 在生产环境中

   python launch.py --api --api-auth="secure_username:complex_password"
   

2. 使用 HTTPS 进行所有 API 通信

   python launch.py --api --tls-keyfile=key.pem --tls-certfile=cert.pem
   

3. 限制本地请求 以防止潜在的 SSRF 攻击

   python launch.py --api --api-forbid-local-requests
   

4. 限制服务器控制 功能，除非需要，否则不要启用 --api-server-stop

5. 启用日志记录 以审计 API 使用情况

   python launch.py --api --api-log
   

6. 考虑网络级安全，例如：

   • 防火墙规则以限制对 API 端口的访问
   • 具有额外安全功能的反向代理
   • 用于 API 访问的 VPN 或专用网络

来源： modules/api/api.py201-205 modules/api/api.py905-916 modules/api/api.py147-165

命令行参考

下表总结了与安全相关的命令行参数

参数	描述
--api-auth	启用身份验证及指定凭据
--api-log	启用 API 请求日志记录
--api-enable-requests	控制 API 是否可以发出出站 HTTP 请求
--api-forbid-local-requests	阻止 API 向本地资源发出请求
--api-useragent	设置 API 请求的用户代理 (User-Agent) 头部
--tls-keyfile	SSL 密钥文件路径
--tls-certfile	SSL 证书文件路径
--api-server-stop	启用服务器控制端点

来源： modules/api/api.py201-252 modules/api/api.py905-916