SAMA 0.37 配置参数详解
SAMA 0.37.2 服务端 .env 环境变量全量详解：按 app/config/default.js 的 app/logger/ws/tcp/db/redis/storage/jwt/http/repl/conversation/push/chatBot/resend/googleAI 分域逐项讲解作用、默认值与实测值，附 JWT 有效期、会话人数上限等 4 项修改-重启-验证闭环与客户端 VITE_* 构建参数说明，2026-10-30 实测。
SAMA 0.37 配置参数详解
目标：讲清 SAMA 0.37.2 服务端的全部配置入口与参数含义。SAMA 没有配置文件，唯一配置载体是环境变量（容器内经
dotenv读/app/.env），代码映射集中在app/config/default.js。本文参数解释基于该文件与源码逐项核对，实测值来自 2026-10-30 Docker 部署（部署过程见 《SAMA 0.37 Docker Compose 部署指南》）。
1. 配置加载机制
- 官方镜像通过
volumes: ./.env.docker:/app/.env挂载配置；npm start以--import dotenv/config加载。 - 读取链路：
process.env.X→CONFIG树 → 各模块经config.get("a.b.c")消费。改配置 = 改 .env + 重启容器：docker compose restart sama-server。 - 少数 compose 层变量（如
MINIO_ENDPOINT）在 composeenvironment中二次覆盖，优先级高于 .env 文件，排查时两处都要看。
2. 应用基础（app.*）
| 环境变量 | 作用 | 默认/实测 |
|---|---|---|
NODE_ENV | 运行环境标识 | 实测 production（官方示例用 testing） |
APP_NAME | 应用显示名 | 默认 SAMA |
HOSTNAME | 覆盖节点主机名（集群/日志标识） | 实测 NodeName；/health 回显 hostname |
CLUSTER_ADVERTISE_IP | 集群对外通告 IP | 多机部署才需要 |
STANDALONE_NODE | 设为 true 时节点不做跨节点转发 | 默认关闭 |
WATCHDOG_PING_SOCKET_INTERVAL | 空闲 socket 看门狗探测间隔（毫秒） | 未设则关闭 |
LOG_LEVEL | 日志级别（debug/info/...） | 默认 debug，生产建议 info |
LOG_SINGLE_LINE | 设 true 时单行日志 | 默认多行 |
3. 监听端口（ws / tcp）
| 环境变量 | 作用 | 默认/实测 |
|---|---|---|
APP_PORT / APP_WS_PORT / PORT | WS+HTTP 统一监听端口（uWS 同端口双协议） | 优先级 APP_WS_PORT>APP_PORT>PORT>9001；实测 9001 |
APP_CLUSTER_PORT | 集群内部端口（ws.cluster.port） | 多节点互联用 |
APP_TCP_PORT | 追加 TCP 透传监听（非 WS 客户端） | 设置即启用；官方测试用 8001/8002 |
SSL_KEY_FILE_NAME / SSL_CERT_FILE_NAME | WS 直接挂 TLS 的证书文件名（/app 下） | 实测留空，TLS 由外层 nginx 终结 |
TLS_KEY_FILE_NAME / TLS_CERT_FILE_NAME | TCP 通道 TLS 证书 | 默认空 |
RUN_NODE_1_CMD / RUN_NODE_2_CMD | 测试编排用：各节点的启动命令串 | 实测 9001/9002 双节点 |
nginx 侧的
upstream loadbalance引用sama-server:9001/9002（PM2 fog 实例），扩节点需同步改 nginx 配置。
4. 数据存储（db / redis / storage）
| 环境变量 | 作用 | 默认/实测 |
|---|---|---|
MONGODB_URL | MongoDB 连接串 | 实测 mongodb://mongo/samadb；库不存在自动创建 |
MONGODB_LOG_QUERIES | 设 true 打印查询日志 | 默认关 |
REDIS_URL | Redis 连接串（优先） | 实测 redis://redis:6379 |
REDIS_HOST/REDIS_PORT/REDIS_PASSWORD/REDIS_DB | 无 URL 时的分项连接 | DB 默认 0 |
STORAGE_DRIVER | 文件存储驱动：minio/s3/spaces | 默认 s3；实测 minio |
MINIO_ENDPOINT | MinIO 主机名（compose 内写服务名 s3） | 实测 s3 |
MINIO_PORT | MinIO API 端口 | 默认 9010；官方 MinIO 容器是 9000，必须显式设 9000（实测） |
MINIO_USE_SSL | 是否 https 连 MinIO | 实测 false |
MINIO_BUCKET_NAME | 附件桶名 | 实测 samabucket |
MINIO_ACCESS_KEY / MINIO_SECRET_KEY | server 用的 S3 服务账号（由 s3-service 容器 mc admin user svcacct add 创建） | 与 ROOT 账号不同，见部署指南 |
MINIO_ROOT_USER / MINIO_ROOT_PASSWORD | 仅 MinIO 容器与管理任务用 | 不给 server |
S3_ACCESS_KEY/S3_ENDPOINT/S3_BUCKET_NAME/S3_REGION 等 | AWS S3 驱动参数 | region 默认 us-east-1 |
SPACES_* | DigitalOcean Spaces 驱动参数 | region 默认 us-east-1 |
FILE_UPLOAD_URL_EXPIRES_IN | 预签名上传 URL 有效期（秒） | 实测 3600（1 小时） |
FILE_DOWNLOAD_URL_EXPIRES_IN | 预签名下载 URL 有效期（秒） | 实测 604800（7 天），get_file_urls 回显中可见 X-Amz-Expires=604800 |
5. 认证与安全（jwt / http）
| 环境变量 | 作用 | 默认/实测 |
|---|---|---|
JWT_ACCESS_SECRET | 访问令牌签名密钥 | 必设，openssl rand -hex 32 |
JWT_ACCESS_TOKEN_EXPIRES_IN | access token 有效期（秒） | 实测 10800（3h）；过期后 WS 收 422 The token has expired.（实测复现） |
JWT_REFRESH_SECRET | 刷新令牌签名密钥 | 必设，可与 access 同值但建议独立 |
JWT_REFRESH_TOKEN_EXPIRES_IN | refresh token 有效期（秒） | 实测 1209600（14 天），以 HttpOnly Cookie 下发 |
COOKIE_SECRET | Cookie 签名密钥（refresh_token signed cookie） | 必设 |
CORS_ORIGIN | HTTP 响应 Access-Control-Allow-Origin | 实测 Web 入口地址；未设时回显请求 origin 或 * |
HTTP_ADMIN_API_KEY | /admin/* 管理端点 Bearer 鉴权 Key | 必设，缺失时管理端点 401 |
6. 业务行为（conversation / operationsLogs / push）
| 环境变量 | 作用 | 默认/实测 |
|---|---|---|
CONVERSATION_MAX_PARTICIPANTS | 群聊/频道人数上限（conversation_create 校验） | 默认 50 |
CONVERSATION_DISABLE_CHANNELS_LOGIC | 设 true 关闭频道"仅 owner/admin 可发言"限制 | 默认开启频道逻辑 |
CONVERSATION_NOTIFICATIONS_ENABLED | 会话事件通知开关 | 默认关 |
CONVERSATION_PRELOAD_COUNT | 会话列表预载数 | 默认 30 |
MESSAGE_PRELOAD_COUNT | 消息列表预载数 | 默认 30 |
SEARCH_PRELOAD_COUNT | 会话搜索结果上限 | 默认 30 |
OPERATIONS_LOG_EXPIRES_IN | 操作日志过期秒数 | 实测 1209600（14 天） |
SAMA_NATIVE_PUSH_QUEUE_NAME | 原生推送 Bull 队列名（配 push-daemon） | 可选组件 |
CHAT_BOT_LOGIN | 服务端 Bot 账号 login（conversation handlers） | 可选 |
RESEND_API_KEY/RESEND_SENDER | Resend 邮件发送（OTP 邮件） | 未配则 OTP 无法发信 |
GOOGLE_GENERATIVE_AI_MODEL | Gemini 模型名（AI 消息改写/Bot） | 可选 |
APP_REPL_* | 运维 REPL（HTTP 5010 端口/socket/file 三模式） | 生产保持关闭 |
7. 修改-重启-验证闭环（实测）
例 1：把群人数上限 50 → 100。 .env.docker 改 CONVERSATION_MAX_PARTICIPANTS=100，docker compose restart sama-server，conversation_create 传入 101 个参与者不再报 There are too many users in the group conversation.（422）。
例 2：缩短 access token 到 30 分钟。 改 JWT_ACCESS_TOKEN_EXPIRES_IN=1800 重启；用旧 token connect 正常，等 30 分钟后返回 {"connect":{"error":{"status":422,"message":"The token has expired."}}}，走 /login 换新 token 恢复（实测过期行为与该错误文案一致）。
例 3：文件下载 URL 降到 1 小时。 改 FILE_DOWNLOAD_URL_EXPIRES_IN=3600 重启，get_file_urls 回显 X-Amz-Expires=3600。
例 4：消息预载 30 → 50。 改 MESSAGE_PRELOAD_COUNT=50 重启后 message_list 单页最多返回 50 条。
8. 客户端侧构建参数（VITE_*）
Web 客户端的连接参数是构建期注入（prefs/client/Dockerfile.frontend 的 build args），改了必须重建 sama-client 镜像：
| 构建参数 | 作用 | 实测值 |
|---|---|---|
VITE_SOCKET_CONNECT | 浏览器 WS 连接地址 | ws://localhost:8162（nginx LB 口） |
VITE_HTTP_CONNECT | 浏览器 HTTP 登录/文件地址 | http://localhost:8162 |
VITE_PUBLIC_VAPID_KEY | Web Push VAPID 公钥 | 官方示例值，生产需自生成 |
VITE_MESSAGES_COUNT_TO_PRELOAD | 前端拉历史消息条数 | 30 |
BRANCH | 构建期克隆的 sama-client 分支 | main（生产建议锁定固定版本） |
注意 8161/8162 是 nginx 的两个 server 块：SPA 静态与 API/WS 分离，浏览器只访问这两个口，不直连 server 的 9001/9002。
9. 相关阅读
部署与踩坑：《SAMA 0.37 Docker Compose 部署指南》；API 端点：《SAMA 0.37 API 详解》；组件定位：《SAMA 0.37 介绍与选型指南》。