安全指南

保护您的 API 密钥和数据安全，遵循企业级安全最佳实践

快速导航

安全概述 API Key 安全 认证授权 加密存储 RBAC 权限 最佳实践 常见问题 安全审计

安全概述

AI Router Platform 采用企业级安全措施保护您的数据和 API 密钥。 所有敏感数据使用 AES-256 加密存储，传输过程使用 HTTPS 加密， 并实施完整的 RBAC 权限控制和审计日志。

AES-256 加密

所有 Provider API Keys 加密存储，密钥环境变量管理

JWT 认证

安全的 Token 认证，24 小时有效期，自动续期

RBAC 权限

细粒度访问控制，3 种角色，多租户隔离

HTTPS 全站加密

所有数据传输使用 TLS 1.3 加密

SQL 注入防护

使用参数化查询，防止 SQL 注入

XSS 防护

Content Security Policy + 输入过滤

审计日志

完整的操作日志记录和追踪

API Key 安全管理

✅ 正确做法 vs ❌ 错误做法

❌ 不要这样做

硬编码 API Key

// ❌ 错误 const API_KEY = "sk-xxxxx";

提交到 Git

# ❌ .env 文件被提交 git add .env git commit -m "add config"

在前端暴露

// ❌ 浏览器中可见 const key = process.env.API_KEY;

✅ 正确做法

使用环境变量

// ✅ 正确 const key = process.env.API_KEY;

添加到 .gitignore

# ✅ .gitignore
.env
.env.local
.env.production

只在后端使用

// ✅ 后端 API 路由
app.post('/api/chat', auth, handler);

使用环境变量

.env 文件

# ⚠️ 重要：不要提交此文件到 Git
AI_ROUTER_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
AI_ROUTER_BASE_URL=https://api.poeti.ai/v1

# JWT Secret（必须至少 32 字节）
JWT_SECRET=your-super-secret-jwt-key-32-bytes-min

# 数据库密码
POSTGRES_PASSWORD=your-strong-database-password

# Provider API Keys（加密存储）
ENCRYPTION_KEY=your-32-byte-encryption-key-here

生成强密钥

# 生成 32 字节随机密钥
openssl rand -base64 32

# 或使用 /dev/urandom
head -c 32 /dev/urandom | base64

代码示例

Python

import os from dotenv import load_dotenv # 加载环境变量 load_dotenv() # ✅ 安全获取 API Key api_key = os.getenv("AI_ROUTER_API_KEY") if not api_key: raise ValueError("API Key 未设置") # 使用 API Key headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" }

Node.js

require('dotenv').config(); // ✅ 安全获取 API Key const apiKey = process.env.AI_ROUTER_API_KEY; if (!apiKey) { throw new Error('API Key 未设置'); } // 使用 API Key（仅在后端） const headers = { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' };

Go

package main

import (
    "os"
    "log"
)

func main() {
    // ✅ 安全获取 API Key
    apiKey := os.Getenv("AI_ROUTER_API_KEY")
    if apiKey == "" {
        log.Fatal("API Key 未设置")
    }

    // 使用 API Key
    req.Header.Set("Authorization", "Bearer " + apiKey)
}

认证与授权

JWT Token 认证

平台使用 JWT (JSON Web Token) 进行用户认证，Token 有效期为 24 小时， 支持自动刷新机制。

认证流程

  1. 用户通过 /v1/auth/login 登录，获取 JWT Token
  2. Token 存储在 localStorage 或 sessionStorage
  3. 后续请求在 Authorization header 中携带 Token
  4. 服务器验证 Token 签名和过期时间
  5. Token 过期自动跳转登录页

HTTP 请求示例

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

密码安全策略

⚠️ 密码要求（已强制执行）

  • 最少 8 个字符
  • 至少 1 个大写字母
  • 至少 1 个小写字母
  • 至少 1 个数字
  • 至少 1 个特殊字符（!@#$%^&*）
❌ 弱密码
  • • password123
  • • 123456789
  • • qwerty
  • • admin123
✅ 强密码
  • • P@ssw0rd!2024
  • • My$ecure#Pass1
  • • Complex!Key@99
  • • Str0ng*P@ssw0rd

推荐：使用密码管理器（如 1Password、LastPass）生成和管理强密码

数据加密

AES-256 加密存储

所有 Provider API Keys 使用 AES-256-GCM 加密存储， 加密密钥通过 ENCRYPTION_KEY 环境变量管理，从不明文存储。

加密流程

  1. 用户提交 Provider API Key
  2. 后端使用 AES-256-GCM 加密
  3. 加密后的数据存储到 PostgreSQL
  4. 使用时解密（仅在内存中）
  5. 日志中 Key 使用 *** 遮掩

加密实现（Go）

// internal/crypto/encryption.go
func Encrypt(plaintext, key string) (string, error) {
    // 1. 创建 AES cipher
    block, _ := aes.NewCipher([]byte(key))

    // 2. 创建 GCM mode
    gcm, _ := cipher.NewGCM(block)

    // 3. 生成随机 nonce
    nonce := make([]byte, gcm.NonceSize())
    io.ReadFull(rand.Reader, nonce)

    // 4. 加密数据
    ciphertext := gcm.Seal(nonce, nonce,
        []byte(plaintext), nil)

    return base64.StdEncoding.EncodeToString(
        ciphertext), nil
}

⚠️ 加密密钥管理

  • 加密密钥必须 32 字节（256 位）
  • 使用强随机生成器生成
  • 存储在环境变量，从不提交到 Git
  • 定期轮换（建议每年）
  • 生产环境与开发环境使用不同密钥

RBAC 权限控制

基于角色的访问控制

平台实施 RBAC (Role-Based Access Control) 权限系统， 提供 3 种内置角色，支持细粒度资源访问控制。

Admin

  • 完整系统权限
  • 管理用户和组织
  • 配置系统设置
  • 查看所有日志
  • 管理计费

Developer

  • 创建 API Keys
  • 调用 API
  • 查看使用统计
  • 查看自己的日志
  • 配置路由策略

Viewer

  • 只读权限
  • 查看统计数据
  • 查看系统状态
  • 无法修改配置
  • 无法创建资源

权限矩阵

资源/操作 Admin Developer Viewer
创建 API Key ✅ ✅ ❌
查看使用统计 ✅ ✅ ✅
管理组织 ✅ ❌ ❌
配置系统设置 ✅ ❌ ❌
查看所有日志 ✅ 仅自己 ❌

安全最佳实践

✅ 应该做

  • 使用强密码和 2FA 双因素认证
  • 定期轮换 API Keys（建议 90 天）
  • 使用最小权限原则（Principle of Least Privilege）
  • 定期审查访问日志和异常行为
  • 配置预算告警，防止账单异常
  • 为不同环境使用不同的 API Keys

❌ 不应该做

  • 在公开代码库中提交 API Keys
  • 在前端 JavaScript 中直接使用 API Keys
  • 与他人共享 API Keys
  • 使用弱密码或默认密码
  • 忽略安全告警和异常登录通知
  • 使用生产环境 Keys 进行测试

常见安全问题

Q: API Key 泄露了怎么办？

⚠️ 立即行动

  1. 立即在控制台删除泄露的 API Key
  2. 生成新的 API Key 并更新应用
  3. 检查使用日志，确认是否有异常调用
  4. 如果发现滥用，联系技术支持
  5. 审查代码，找出泄露原因并修复

Q: 如何防止 XSS 攻击？

系统已实施多层 XSS 防护：Content Security Policy (CSP)、输入过滤、输出转义。

开发者注意事项：

  • 使用 textContent 而非 innerHTML 插入用户输入
  • 如需插入 HTML，使用 DOMPurify 净化
  • 避免使用 eval() 或 new Function()

Q: 如何配置 IP 白名单？

API Key 支持 IP 白名单功能，只允许特定 IP 地址调用。 

# 在控制台配置 API Key 时添加
allowed_ips:
  - 203.0.113.0/24
  - 198.51.100.42

安全审计报告

平台已完成全面安全审计（2026-03-25），修复所有高危和中危漏洞。 审计范围包括：前端、后端、配置、基础设施。

✅ 0

高危漏洞

✅ 0

中危漏洞

✅ 8

已修复问题

已修复的关键问题

  • P0 JWT Secret 硬编码 → 环境变量 + 强度验证（32+ 字节）
  • P0 SQL 注入风险 → 参数化查询
  • P1 密码强度不足 → 强制密码策略（8+ 字符，大小写+数字+特殊字符）
  • P1 敏感信息日志泄露 → API Keys 遮掩显示
  • P1 XSS 风险 → CSP + 输入过滤 + DOMPurify

完整安全审计报告：SECURITY_AUDIT_REPORT.md