配置参考
XSI 的配置分为三层:
| 层级 | 位置 | 生效方式 |
|---|
| 部署级 | API 与控制台容器的环境变量(本页) | 启动时读取一次,修改后需重启 |
| 租户级 | Redis 中的租户配置,通过 /x-config 或配置管理控制台修改 | 立即生效,自动同步到所有实例,见《租户配置 API》 |
| 账号级 | 账号记录,通过 /x-users 或账户管理控制台修改 | 立即生效,见《账号管理 API》 |
读取规则:环境变量只要存在就生效,即使是空字符串(例如 EMAIL_SMTP: "" 得到的是空值而不是默认值)。整数类变量无法解析或低于下限时使用默认值;时长类变量支持 90m、2h 或整数秒,低于下限时取下限;列表类变量用 , 或 ; 分隔,不要在分隔符后加空格。
部分变量名以 XAI_ 开头,这是历史命名,与 XSI 的功能一致。
连接与初始化
| 变量 | 默认值 | 说明 |
|---|
PORT | 3443 | HTTP 监听端口 |
POSTGRES_DSN | — | PostgreSQL 连接串(GORM 格式),连接失败时进程退出;首次启动自动建表与索引 |
REDIS_ADDR、REDIS_PASS、REDIS_DB | —、—、0 | 主 Redis |
MAIL_REDIS_ADDR、MAIL_REDIS_PASS | 同主 Redis | 邮件队列与注册防刷使用的 Redis |
MAIL_REDIS_DB | 1 | 邮件队列 DB,最小为 1;须与邮件服务的 REDIS_DB 一致 |
INIT_USERS | — | 初始账号,格式 名称::邮箱::Key,多个用 , 分隔。只创建不存在的账号,不会更新已有账号。名为 root 的账号成为平台 root,应排在首位;Key 必须是 51 位 sk-Xvs 格式 |
部署模式
| 变量 | 默认值 | 说明 |
|---|
SINGLE_TENANT | true | true:自助注册账号加入 root 租户;false:每个注册用户成为独立租户 |
SINGLE_MODE | true | true:单实例,计数与通知在进程内;false:多实例,通过 Redis 共享。只有字面值 false 关闭 |
TRUSTED_PROXY_CIDRS | 回环地址与 RFC 1918 私网 | 受信任的反向代理网段,只有来自这些地址的连接才读取转发头中的客户端 IP |
TZ | 镜像默认 | 时区,决定日期统计、日额度与 RPD/TPD 的切换时间 |
站点地址
用于邮件内容、激活链接与控制台跳转。只写主机名,不要带协议或路径。
| 变量 | 默认值 | 说明 |
|---|
XAI_SVC | xsirouter.com | 站点主域名 |
XAI_API | api.<XAI_SVC> | API 地址,激活链接为 https://<XAI_API>/x-sign/activate |
XAI_ADMIN | admin.<XAI_SVC> | 配置管理控制台 |
XAI_MANAGE | manage.<XAI_SVC> | 账户管理控制台 |
XAI_DOCS | docs.<XAI_SVC> | 文档站 |
XAI_MAIL | 内置值 | 平台通知收件人;租户未配置 XAI_MAIL 时使用。代码内置的默认收件人不属于你的组织,部署时必须设为自己的邮箱(在 Compose 模板中与 root 邮箱一同设置) |
QR_CODE | — | 默认客服二维码 URL |
注册
| 变量 | 默认值 | 说明 |
|---|
SIGN_ENABLE | true | 是否开放自助注册 |
SAFE_ENABLE | true | 注册反滥用(按 IP 与邮箱的频率限制) |
XAI_CREDIT | 单租户 2,多租户 120 | 注册赠金(1 个月有效);部署模板设为 0 |
XAI_REFERRAL_REWARD_RATE | 0.05 | 推荐奖励比例,范围 0–0.1;0 关闭推荐码 |
账号与计费
| 变量 | 默认值 | 说明 |
|---|
USER_FILTER | true | 是否执行准入检查(IP、状态、额度、限速、白名单)与 XAPI_FEE。false 仅适合完全受信的内部环境,计费仍照常进行 |
USER_MIN_BALANCE | 1 | 冻结阈值(余额低于该值减 0.01 时冻结),也是新子账号的最低额度;下限 1 |
USER_API_BALANCE | 100 | 管理者权限所需的最低余额;下限 2 |
XAPI_FEE | 0.012 | 非模型类操作的固定手续费,上限 0.24 |
MONTHLY_USER_CREDIT | 3000 | 订阅账号(Role 3)的默认每月额度单位;下限 100 |
STATS_INTERVAL | 1000 | 账号状态落盘频率:每 N 次请求同步 Redis,每 10N 次写 PostgreSQL;下限 10 |
SYNC_ENABLE | false | 每次请求都同步账号状态到 Redis(调试用,有性能开销) |
请求与上游
| 变量 | 默认值 | 说明 |
|---|
REQUEST_BODY_LIMIT_BYTES | 209715200(200 MiB) | 解压后的请求体上限;0 不限制 |
RESPONSE_HEADER_TIMEOUT_SECS | 1800 | 等待上游响应头的最长时间(秒) |
MASK_ERRORS | false | 用统一 JSON 替换所有 ≥ 400 的上游错误正文 |
LOG_ENABLE | false | 记录请求体日志(排障用,注意隐私) |
AZURE_AI_APIVERSION | — | Azure 的默认 api-version |
AZURE_AI_APIVERSION_CHAT、_RESPONSES、_EMBEDDINGS、_IMAGES、_AUDIO、_REALTIME | — | 按接口类型指定 Azure api-version;Key 的 config.api_versions 优先 |
重试、休眠与故障转移
| 变量 | 默认值 | 说明 |
|---|
NO_RETRY_STATUS | 200,400,403,404,405,413,421,422,499,500 | 不重试、也不计入模型失败的上游状态码 |
STATUS_CODES | 429,401,402,503,408,524 | 触发 Key 自动休眠的上游状态码 |
KEY_BACK | 60 | 自动休眠时长(分钟),下限 3 |
AUTO_DISABLE_KEY_STATUS | — | 触发 Key 自动禁用的状态码,例如 401 |
AUTO_DELETE_KEY_STATUS | — | 触发 Key 自动删除的状态码;与上一项重复时删除优先 |
MODEL_FAILOVER_THRESHOLD | 3 | 模型连续失败多少次触发分组切换或模型故障替换 |
SWITCH_OVER_TTL | 1h | 分组切换持续时间,下限 1 分钟 |
MODEL_FAILOVER_TTL | 1h | 模型故障替换持续时间,下限 1 分钟 |
STICKY_SCHEDULER | true | 全局粘性调度;false 时只对租户 STICKY_LEVELS 生效 |
STICKY_BINDING_TTL | 24h | 会话与 Key 的绑定保留时间 |
WebSocket
| 变量 | 默认值 | 说明 |
|---|
WS_MAX_CONN_DURATION | 60m | 单个 WebSocket 连接的最长时间,下限 5 分钟 |
WS_WRITE_TIMEOUT | 15s | WebSocket 写超时,下限 3 秒 |
WS_DASHSCOPE_REALTIME_MAX_CONN_DURATION | 120m | DashScope Realtime 连接最长时间 |
WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS | 3 | Responses WebSocket 首次连接上游时尝试的 Key 数 |
WS_RESPONSES_MAX_TURN_RETRIES | 2 | Responses WebSocket 每轮的重试次数 |
用量估算与文件
| 变量 | 默认值 | 说明 |
|---|
SESSION_USAGE_TTL | 30m | 会话最近一次真实用量的保留时间,用于估算中断请求的用量 |
SESSION_USAGE_LIMIT | 100000 | 上述缓存的条目上限 |
USAGE_ESTIMATE_ALERT_CREDIT | 100 | 某账号当日估算计费达到该金额时记录告警日志 |
USAGE_ESTIMATE_ALERT_SHARE | 0.3 | 且估算部分占当日费用的比例不低于该值 |
FILE_REGISTRY_TTL | 3 年 | DeepSeek 文件归属登记的保留时间 |
邮件
API 不直接连接 SMTP,而是把邮件写入 Redis 队列,由 proxyxai/mail 服务投递。
| 变量 | 说明 |
|---|
EMAIL_SMTP、EMAIL_PORT、EMAIL_AUTH、EMAIL_PASS、EMAIL_SENDER | 租户邮件配置的默认值。部署模板将 API 容器的 EMAIL_SMTP、EMAIL_AUTH、EMAIL_PASS 设为空字符串,由邮件服务统一投递;请勿依赖代码内置的默认值 |
EMAIL_FOOTER_YEAR | 邮件页脚年份,默认当前年份 |
邮件服务(xsirouter-mail)的变量:REDIS_ADDR、REDIS_DB(1)、EMAIL_SMTP、EMAIL_PORT、EMAIL_TLS、EMAIL_AUTH、EMAIL_PASS、EMAIL_WORKERS、REDIS_POP_TIMEOUT。
控制台容器
控制台容器启动时把以下变量渲染为浏览器端的 config.js。未设置的变量为空。
| 变量 | 说明 |
|---|
XAI_API | API 地址;未设置时使用 api.<当前主域> |
XAI_ADMIN、XAI_MANAGE | 两个控制台互相跳转的地址 |
BRAND_NAME | 控制台品牌名 |
XPAY_API | 支付网关租户地址,须包含 /t/<tenant>;为空时不启用钱包、商品与收入统计 |
SUPPORT_QR_URL | 客服二维码 |
XAI_CARD_API | 非空时品牌标识链接指向本站 |
XAI_HIDE_MODEL_PRICING | 设为 true 时隐藏“模型与价格”链接 |
XAI_PLATFORM_MODE | 控制台展示模式 |
XAI_REFERRAL_REWARD_RATE | 前端显示的推荐奖励比例,应与 API 的同名变量一致 |
LICENSE_ID | 商业授权编号,显示授权核验入口 |
价格表
API 镜像在工作目录 /home/nonroot 中包含 pricing.json。以二进制方式运行时,请在 pricing.json 所在目录启动进程;文件缺失时 XSI 会退回一份内置的最小价格表,系统级模糊匹配失效(租户自定义的模型仍可参与匹配)。日常调价建议使用租户 PRICING,无需重启。
相关文档