配置参考

XSI 的配置分为三层:

层级位置生效方式
部署级API 与控制台容器的环境变量(本页)启动时读取一次,修改后需重启
租户级Redis 中的租户配置,通过 /x-config 或配置管理控制台修改立即生效,自动同步到所有实例,见《租户配置 API》
账号级账号记录,通过 /x-users 或账户管理控制台修改立即生效,见《账号管理 API》

读取规则:环境变量只要存在就生效,即使是空字符串(例如 EMAIL_SMTP: "" 得到的是空值而不是默认值)。整数类变量无法解析或低于下限时使用默认值;时长类变量支持 90m、2h 或整数秒,低于下限时取下限;列表类变量用 , 或 ; 分隔,不要在分隔符后加空格。

部分变量名以 XAI_ 开头,这是历史命名,与 XSI 的功能一致。

连接与初始化

变量默认值说明
PORT3443HTTP 监听端口
POSTGRES_DSN—PostgreSQL 连接串(GORM 格式),连接失败时进程退出;首次启动自动建表与索引
REDIS_ADDR、REDIS_PASS、REDIS_DB—、—、0主 Redis
MAIL_REDIS_ADDR、MAIL_REDIS_PASS同主 Redis邮件队列与注册防刷使用的 Redis
MAIL_REDIS_DB1邮件队列 DB,最小为 1;须与邮件服务的 REDIS_DB 一致
INIT_USERS—初始账号,格式 名称::邮箱::Key,多个用 , 分隔。只创建不存在的账号,不会更新已有账号。名为 root 的账号成为平台 root,应排在首位;Key 必须是 51 位 sk-Xvs 格式

部署模式

变量默认值说明
SINGLE_TENANTtruetrue:自助注册账号加入 root 租户;false:每个注册用户成为独立租户
SINGLE_MODEtruetrue:单实例,计数与通知在进程内;false:多实例,通过 Redis 共享。只有字面值 false 关闭
TRUSTED_PROXY_CIDRS回环地址与 RFC 1918 私网受信任的反向代理网段,只有来自这些地址的连接才读取转发头中的客户端 IP
TZ镜像默认时区,决定日期统计、日额度与 RPD/TPD 的切换时间

站点地址

用于邮件内容、激活链接与控制台跳转。只写主机名,不要带协议或路径。

变量默认值说明
XAI_SVCxsirouter.com站点主域名
XAI_APIapi.<XAI_SVC>API 地址,激活链接为 https://<XAI_API>/x-sign/activate
XAI_ADMINadmin.<XAI_SVC>配置管理控制台
XAI_MANAGEmanage.<XAI_SVC>账户管理控制台
XAI_DOCSdocs.<XAI_SVC>文档站
XAI_MAIL内置值平台通知收件人;租户未配置 XAI_MAIL 时使用。代码内置的默认收件人不属于你的组织,部署时必须设为自己的邮箱(在 Compose 模板中与 root 邮箱一同设置)
QR_CODE—默认客服二维码 URL

注册

变量默认值说明
SIGN_ENABLEtrue是否开放自助注册
SAFE_ENABLEtrue注册反滥用(按 IP 与邮箱的频率限制)
XAI_CREDIT单租户 2,多租户 120注册赠金(1 个月有效);部署模板设为 0
XAI_REFERRAL_REWARD_RATE0.05推荐奖励比例,范围 0–0.1;0 关闭推荐码

账号与计费

变量默认值说明
USER_FILTERtrue是否执行准入检查(IP、状态、额度、限速、白名单)与 XAPI_FEE。false 仅适合完全受信的内部环境,计费仍照常进行
USER_MIN_BALANCE1冻结阈值(余额低于该值减 0.01 时冻结),也是新子账号的最低额度;下限 1
USER_API_BALANCE100管理者权限所需的最低余额;下限 2
XAPI_FEE0.012非模型类操作的固定手续费,上限 0.24
MONTHLY_USER_CREDIT3000订阅账号(Role 3)的默认每月额度单位;下限 100
STATS_INTERVAL1000账号状态落盘频率:每 N 次请求同步 Redis,每 10N 次写 PostgreSQL;下限 10
SYNC_ENABLEfalse每次请求都同步账号状态到 Redis(调试用,有性能开销)

请求与上游

变量默认值说明
REQUEST_BODY_LIMIT_BYTES209715200(200 MiB)解压后的请求体上限;0 不限制
RESPONSE_HEADER_TIMEOUT_SECS1800等待上游响应头的最长时间(秒)
MASK_ERRORSfalse用统一 JSON 替换所有 ≥ 400 的上游错误正文
LOG_ENABLEfalse记录请求体日志(排障用,注意隐私)
AZURE_AI_APIVERSION—Azure 的默认 api-version
AZURE_AI_APIVERSION_CHAT、_RESPONSES、_EMBEDDINGS、_IMAGES、_AUDIO、_REALTIME—按接口类型指定 Azure api-version;Key 的 config.api_versions 优先

重试、休眠与故障转移

变量默认值说明
NO_RETRY_STATUS200,400,403,404,405,413,421,422,499,500不重试、也不计入模型失败的上游状态码
STATUS_CODES429,401,402,503,408,524触发 Key 自动休眠的上游状态码
KEY_BACK60自动休眠时长(分钟),下限 3
AUTO_DISABLE_KEY_STATUS—触发 Key 自动禁用的状态码,例如 401
AUTO_DELETE_KEY_STATUS—触发 Key 自动删除的状态码;与上一项重复时删除优先
MODEL_FAILOVER_THRESHOLD3模型连续失败多少次触发分组切换或模型故障替换
SWITCH_OVER_TTL1h分组切换持续时间,下限 1 分钟
MODEL_FAILOVER_TTL1h模型故障替换持续时间,下限 1 分钟
STICKY_SCHEDULERtrue全局粘性调度;false 时只对租户 STICKY_LEVELS 生效
STICKY_BINDING_TTL24h会话与 Key 的绑定保留时间

WebSocket

变量默认值说明
WS_MAX_CONN_DURATION60m单个 WebSocket 连接的最长时间,下限 5 分钟
WS_WRITE_TIMEOUT15sWebSocket 写超时,下限 3 秒
WS_DASHSCOPE_REALTIME_MAX_CONN_DURATION120mDashScope Realtime 连接最长时间
WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS3Responses WebSocket 首次连接上游时尝试的 Key 数
WS_RESPONSES_MAX_TURN_RETRIES2Responses WebSocket 每轮的重试次数

用量估算与文件

变量默认值说明
SESSION_USAGE_TTL30m会话最近一次真实用量的保留时间,用于估算中断请求的用量
SESSION_USAGE_LIMIT100000上述缓存的条目上限
USAGE_ESTIMATE_ALERT_CREDIT100某账号当日估算计费达到该金额时记录告警日志
USAGE_ESTIMATE_ALERT_SHARE0.3且估算部分占当日费用的比例不低于该值
FILE_REGISTRY_TTL3 年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_APIAPI 地址;未设置时使用 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,无需重启。

相关文档