安全配置

范围说明

本页仅涉及用户认证、限流、密钥管理。 智能体工具拦截与文件 / 跨目录访问控制见 工具安全与文件访问控制。

配置 TPCLAW 的安全相关选项。

用户认证

基础认证

security:
  requireAuth: true
  jwtSecretKey: "your-secret-key"        # 生产环境必须修改
  jwtExpireTime: 24                       # JWT 过期时间（小时）
  jwtIssuer: "tpclaw"
  defaultUsername: "admin"
  users:
    admin: "admin-password"               # 管理员账户
    viewer: "viewer-password"             # 普通用户账户

用户角色

认证通过后，系统根据用户名自动分配角色：

角色	条件	权限
admin	用户名为 admin	所有权限，包括技能上传、删除等管理操作
user	其他用户	普通权限，可使用对话、查看配置等

TIP

只有 admin 用户可以执行技能上传、创建、更新、删除等全局管理操作。

API Key 认证

用户配置支持 password:apiKey 格式，同时支持密码和 API Key 认证：

security:
  users:
    admin: "admin-password:your-api-key"

使用 API Key 认证：

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:9527/api/v1/agents

限流配置

通过 rate_limit 配置防止 API 被滥用：

security:
  rate_limit:
    enabled: true
    default:
      rps: 30                    # 默认每秒请求数
      burst: 60                  # 默认突发容量
    rules:
      auth:                      # 含 "auth" 的路径使用更严格的限流
        rps: 3
        burst: 5

配置项	类型	默认值	说明
enabled	bool	false	是否启用限流
default.rps	float	30	默认每秒请求数
default.burst	int	60	默认突发容量
rules	map	-	按路径关键字匹配的限流规则，key 为路径关键字

TIP

rules 中的 key 是路径关键字，系统通过 strings.Contains(path, key) 匹配。例如 auth 会匹配 /api/v1/auth/login 和 /api/v1/auth/token 等路径。

敏感信息管理

环境变量

在配置文件中使用 ${VAR} 语法引用环境变量：

models:
  providers:
    openai:
      api_key: "${OPENAI_API_KEY}"

支持带默认值的语法（如果环境变量不存在则使用默认值）：

api_key: "${OPENAI_API_KEY:-sk-default-key}"

使用密钥管理服务

生产环境推荐使用专业的密钥管理服务：

• HashiCorp Vault
• AWS Secrets Manager
• Azure Key Vault

最佳实践

1. 不要将敏感信息提交到版本控制
2. 使用环境变量存储密钥
3. 定期轮换 API Key
4. 限制 API Key 的权限范围

相关文档

• 配置文件 - 主配置文件