Teable 1.10 配置参数详解

Teable 1.10.0 环境变量逐项实测：默认值、必填性与真实行为（时区/日志级别/数据库连接失败/缓存内置 Redis 兜底/会话 Cookie/13 个安全密钥回退告警/PASSWORD_LOGIN_DISABLED 路由移除等），附 22 项实测汇总表与 FAQ。

TeableTeable2026/10/18

Teable 1.10 配置参数详解

目标：逐项讲清 Teable 1.10.0 的环境变量配置体系——默认值、必填性、实测行为与常见误配。全部「默认值」结论来自官方发布件内置环境变量与官方文档 env 页（查询日期 2026-10-18），全部「实测行为」均在 Ubuntu 22.04.4 + Teable 1.10.0（Standalone，主实例 8105 端口 + 临时实测实例 8107 端口）环境逐项验证。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS（x86_64，12 核 / 32GB 内存）
  • Teable：1.10.0（发布件构建标识 release.2026-10-16T07-06-34Z.3445）
  • 部署形态：Standalone（应用 + PostgreSQL 15.4 + Redis 7.2.4，编排与部署过程见《Teable Docker Compose 部署指南》，主实例对外端口 8105）
  • 临时实测实例：同一网络内另起应用实例（对外端口 8107，独立 PostgreSQL 15.4 与独立附件数据卷），用于参数默认值与故障行为实测，不与主实例共享数据
  • 实测日期：2026-10-18
  • 参数来源核验：官方文档 https://help.teable.ai/en/deploy/env （2026-10-18 抓取）+ 发布件内置环境变量实测（docker inspect ghcr.io/teableio/teable:latest 的镜像配置，镜像内置 TZ=UTC、NODE_ENV=production、PORT=3000、NEXTJS_DIR=enterprise/app-ee、BUILD_VERSION=release.2026-10-16T07-06-34Z.3445、GIT_COMMIT_SHA=fef0615eb0c228e0d3afdb8e50cf21349bcb7868、PREVIEW_TAG=）

说明：Teable 没有主配置文件，全部参数经环境变量注入（Compose 部署走 .env 或编排文件 environment: 段）。修改后必须重建服务才会生效，见第十五章 FAQ Q1。

二、参数体系总览

2.1 参数生效链路

启动脚本按以下顺序处理环境变量（实测行为还原）：

  1. 镜像内置默认：TZ=UTC、NODE_ENV=production、PORT=3000 等烧录在发布件中，不配置时以此兜底；
  2. 部署注入：Compose 读取 .env 注入（本部署主实例注入了数据库/缓存连接、时区、对外地址）；
  3. 入口脚本兜底：未提供 Redis 连接时，入口脚本自动拉起内置 Redis 并注入对应连接变量（实测见第五章 5.3）；
  4. 密钥回退：安全密钥类变量缺失时不阻断启动，回退到「公开的内置默认值」并打印完整告警块（实测见第七章 7.2）；
  5. 校验层检查：应用启动时经 Joi schema 校验（env.validation.schema.ts），非法取值直接拒绝启动。

2.2 参数分组速查

分组核心变量必填详解章节
基础与启动TZ/TIMEZONE、PORT、LOG_LEVEL、LOG_FORMAT—第三章
数据库PRISMA_DATABASE_URL、PRISMA_TRANSACTION_TIMEOUT 等✅第四章
缓存与队列BACKEND_CACHE_PROVIDER、BACKEND_CACHE_REDIS_URI✅（URI）第五章
地址与会话PUBLIC_ORIGIN、BACKEND_SESSION_EXPIRES_IN、BACKEND_JWT_EXPIRES_IN✅（地址）第六章
安全密钥SECRET_KEY 及 13 个密钥槽位建议（缺省回退公开值）第七章
认证与登录PASSWORD_LOGIN_DISABLED、OAuth/OIDC 组、TURNSTILE_*—第八章
存储BACKEND_STORAGE_PROVIDER 及各存储后端变量组—第九章
邮件BACKEND_MAIL_*（建议改用管理面板配置）—第十章
资源限额MAX_COPY_CELLS、TABLE_LIMIT_*—第十一章
自动化/AIAUTOMATION_*、SANDBOX_*、TEABLE_INFRA_*AI 形态必填第十二章
开关与遥测RECORD_HISTORY_DISABLED、TELEMETRY_REPORT_DISABLED 等—第十三章

三、基础与启动参数

3.1 时区：TZ / TIMEZONE

属性值
默认值UTC（发布件内置）
必填否
官方示例Asia/Shanghai

实测：未配置时日志时间为 UTC；编排 .env 中 TIMEZONE=Asia/Shanghai（经 TZ=${TIMEZONE} 注入）后，启动日志显示：

> System Time Zone: Asia/Shanghai
> Current System Time: Sun Oct 18 2026 20:10:34 GMT+0800 (China Standard Time)

⚠️ 注意：PostgreSQL 服务需同样注入 TZ（官方编排已包含），否则数据库时区与应用时区不一致会影响日期字段默认值展示。

3.2 监听端口：PORT

属性值
默认值3000（发布件内置）
实测启动日志 > Ready on http://localhost:3000
改法建议一般不动应用内端口，改宿主机映射（如 8105:3000）即可

3.3 运行环境：NODE_ENV

属性值
默认值production（发布件内置）
校验Joi 仅允许 test / development / production
实测启动日志 > NODE_ENV is production

3.4 版本标识：BUILD_VERSION / GIT_COMMIT_SHA

属性值
默认值release.2026-10-16T07-06-34Z.3445 / fef0615eb0c228e0d3afdb8e50cf21349bcb7868（发布件内置，只读）
用途核对运行中的发布件与官方 Release 的对应关系（该 commit 的 @teable/core 包版本 1.10.0）

3.5 日志级别：LOG_LEVEL

属性值
默认值info
取值fatal / error / warn / info / debug / trace（Joi 校验，越界值拒绝启动）
官方说明应用日志走 pino 结构化输出，"level":30 为 info、40 为 warn、50 为 error、20 为 debug

实测（默认 info，主实例全量日志级别统计）：

4157 "level":30
   36 "level":40
    2 "level":50

实测（LOG_LEVEL=debug，临时实例重启后出现 20 级日志）：

{"level":20,"time":1792326517338,"pid":223,"hostname":"5d87fdace005","name":"teable","context":"OpenApiDocs","msg":"OpenAPI routes without a serving controller: GET /billing/subscription/summary, ..."}
{"level":20,"time":1792326519971,"pid":223,"hostname":"5d87fdace005","name":"teable","context":"WsGateway","msg":"SockJS v0.5.0 bound to \"/socket\""}

💡 说明：默认级别下就能看到 warn/error（如集成未配置的提示），一般无需调到 debug；排障连接/队列问题时临时切 debug。

3.6 日志格式：LOG_FORMAT

属性值
默认值json（实测主实例输出为 pino JSON 行）
取值json / raw
官方示例json

💡 说明：接日志采集系统（Loki/ELK）保持 json；人工排查想看纯文本时改 raw。

四、数据库连接参数

4.1 主数据库连接：PRISMA_DATABASE_URL

属性值
默认值无（必填，官方标注 "must be configured"）
格式postgresql://用户:密码@主机:端口/库名
本部署实测值postgresql://teable:q1w2e3r4@teable-db:5432/teable
兼容写法DATABASE_URL（老版本变量名，仍被识别）

实测（连接串指向不存在的主机，服务启动失败退出）：

Migrate Deploy Error: undefined
Error: getaddrinfo EAI_AGAIN teable-1-10-0-deadhost

服务状态 Exited (1)，健康检查端口无响应。结论：连接串错误在启动期迁移阶段即失败，不会带病运行——这是排查「应用起不来」的第一检查点。

实测（正确连接串，首次启动自动完成全量迁移）：

meta database target: teable-db:5432 (postgresql)
Running meta database migration...
255 migrations found in prisma/migrations
meta database migration completed

💡 说明：仅支持 PostgreSQL 作为主库；连接串建议与官方 Standalone 编排保持一致，库名默认 teable。

4.2 事务超时：PRISMA_TRANSACTION_TIMEOUT / PRISMA_TRANSACTION_MAX_WAIT / BIG_TRANSACTION_TIMEOUT

变量默认值说明
PRISMA_TRANSACTION_TIMEOUT5000单事务最大执行毫秒数；批量更新外键多的记录时官方建议调大
PRISMA_TRANSACTION_MAX_WAIT2000从连接池等待事务连接的最大毫秒数
BIG_TRANSACTION_TIMEOUT600000大型内部事务（如整项目导出）的超时毫秒数

实测：默认值下正常建表/导入均无事务超时；未做压测性调参，遵循官方默认。

五、缓存与队列参数

5.1 缓存提供方：BACKEND_CACHE_PROVIDER

属性值
默认值官方文档标注 sqlite；实际行为见 5.3 实测——未配置任何缓存变量时入口脚本会自动拉起内置 Redis 并注入连接，等效 redis
取值sqlite / memory / redis

源码佐证（发布件对应仓库 cache.config.ts）：

provider: (process.env.BACKEND_CACHE_PROVIDER ??
  (process.env.BACKEND_CACHE_REDIS_URI ? 'redis' : 'sqlite')) as 'memory' | 'sqlite' | 'redis',
sqlite: { uri: process.env.BACKEND_CACHE_SQLITE_URI ?? 'sqlite://.assets/.cache.db' },

5.2 Redis 连接：BACKEND_CACHE_REDIS_URI

属性值
默认值无（官方标注必填——「computed task delivery 必需」，同时作为 provider=redis 时的缓存连接）
格式redis://default:密码@主机:6379/库号
本部署实测值redis://default:q1w2e3r4@teable-cache:6379/0
附加能力计算任务/自动化队列的投递通道（BullMQ）

实测（主实例注入外部 Redis）：启动日志出现 Skipping the registration of FallbackQueueModule（回退队列模块未注册，说明外部 Redis 队列已接管），且未出现内部 Redis 启动信息。

5.3 内置 Redis 兜底行为（重要实测发现）

未提供任何缓存变量（既无 BACKEND_CACHE_REDIS_URI 也无 BACKEND_CACHE_PROVIDER）的实测实例启动日志：

Starting internal Redis...
Waiting for Redis to start...
✓ Internal Redis started successfully (took 2 attempts)
[Nest] 222 - 8:32:19 PM DEBUG [ConditionalModule] (env)=>!env.BACKEND_CACHE_REDIS_URI evaluated to false. Skipping the registration of FallbackQueueModule

服务健康检查通过：

{"status":"ok","info":{"metaDatabase":{"responseTime":5,"status":"up"}},"error":{},"details":{"metaDatabase":{"responseTime":5,"status":"up"}}}

结论：1.10.0 官方发布件在缺少 Redis 配置时会自动拉起内置 Redis（进程内 localhost:6379，实测监听端口确认为 6379）并自动注入连接变量，应用照常可用。这意味着：

  • 最小可用部署可以只有「应用 + PostgreSQL」两个服务；
  • 单机多进程共享缓存/队列时内置 Redis 不可跨服务共享，多服务编排（官方推荐形态）仍应外置 Redis；
  • 内置 Redis 数据随应用服务生命周期，持久化与监控不受控，生产环境不要依赖该兜底。

5.4 性能缓存：BACKEND_PERFORMANCE_CACHE

属性值
默认值无（可选）
作用查询结果性能缓存，官方建议与 BACKEND_CACHE_REDIS_URI 分开用独立 Redis 实例
官方示例redis://default:teable@127.0.0.1:6379/0

实测：本部署未启用（小规模单机场景收益有限）；多用户高并发协作场景按官方建议启用。

六、访问地址与会话参数

6.1 对外地址：PUBLIC_ORIGIN

属性值
默认值无（必填，官方描述 "must be set to your app's access address"）
本部署实测值http://127.0.0.1:8105
影响面头像 URL、邀请链接、分享链接、邮件内链接的生成基准

实测（注册接口回显，头像 URL 前缀即 PUBLIC_ORIGIN）：

{"id":"usrmBbQTvZwObJ4ugW8", "email":"admin@teable.local", "isAdmin":true,
 "avatar":"http://127.0.0.1:8105/api/attachments/read/public/avatar/usrmBbQTvZwObJ4ugW8", ...}

⚠️ 注意：域名/反向代理部署时必须改成对外真实地址（如 https://teable.example.com），否则页面内出现的资源与分享链接不可用；修改后需重建服务（FAQ Q1）。

6.2 会话有效期：BACKEND_SESSION_EXPIRES_IN

属性值
默认值7d
说明服务端登录会话有效期（会话数据在服务端，超期需重新登录）

实测（登录响应的 Cookie 属性）：Set-Cookie: auth_session=...; Expires=Mon, 18 Oct 2027 18:11:20 GMT; HttpOnly; SameSite=Lax——浏览器侧 Cookie 持久化 1 年，但服务端会话按 7d 过期，两者是两层机制，不要混淆。

属性值
默认值false
建议值HTTPS 部署改 true（Cookie 仅经 HTTPS 传输）

6.4 JWT 有效期：BACKEND_JWT_EXPIRES_IN

属性值
默认值20d
说明认证/分享/插件 JWT 的有效期；BACKEND_JWT_SECRET 未设置时签名密钥回退 SECRET_KEY

6.5 重置密码邮件有效期：BACKEND_RESET_PASSWORD_EMAIL_EXPIRES_IN

属性值
默认值30m

七、安全密钥参数

7.1 密钥槽位清单（官方 env 页 + 启动告警块双源核对）

密钥变量用途推荐生成方式
SECRET_KEY根密钥：JWT/会话回退、BYODB URL 派生、EE 环境变量加密、AI 配置加密、邀请码 HMAC、插件密钥回退openssl rand -base64 32
BACKEND_JWT_SECRET认证/分享/插件 JWT 签名（回退 SECRET_KEY）openssl rand -base64 32
BACKEND_SESSION_SECRET登录会话 Cookie 签名（回退 SECRET_KEY）openssl rand -base64 32
BACKEND_ENV_VARIABLE_SECRETEE 应用环境变量加密（HKDF 根，回退 SECRET_KEY）openssl rand -base64 32
BACKEND_AI_CONFIG_ENCRYPTION_SECRETAI 服务商 API Key 加密（HKDF 根，回退 SECRET_KEY）openssl rand -base64 32
BACKEND_MAIL_ENCRYPTION_KEY / _IV邮件退订链接令牌加密openssl rand -hex 8
BACKEND_STORAGE_ENCRYPTION_KEY / _IV附件访问令牌加密（local 存储时必需）openssl rand -hex 8
BACKEND_ACCESS_TOKEN_ENCRYPTION_KEY / _IV个人访问令牌加密openssl rand -hex 8
BACKEND_DATA_DB_URL_ENCRYPTION_KEY / _IVBYODB 数据库 URL 加密openssl rand -hex 8
SANDBOX_JWT_SECRETAI 沙箱会话签名（沙箱服务须与应用一致）openssl rand -base64 32

7.2 缺省回退行为（实测告警块全文）

未配置任何密钥时实例照常启动，日志打印完整安全告警（主实例实测，[sandbox] 行为内置沙箱组件的同源告警）：

SECURITY WARNING: missing secret environment variable(s) — the instance will START anyway, falling back to the built-in PUBLICLY KNOWN defaults (they live in the public git history, so anyone can forge tokens / decrypt data protected by them):

  - SECRET_KEY: JWT/session fallback, BYODB URL key derivation, EE env-variable encryption, AI-config key encryption, invitation-code HMAC, welcome-reward inbox HMAC, plugin secret fallback
  - BACKEND_JWT_SECRET (or SECRET_KEY): signing auth / share / plugin JWTs
  - BACKEND_SESSION_SECRET (or SECRET_KEY): signing login session cookies
  - BACKEND_ENV_VARIABLE_SECRET (or SECRET_KEY): encrypting EE app env variables (HKDF root)
  - BACKEND_AI_CONFIG_ENCRYPTION_SECRET (or SECRET_KEY): encrypting AI provider API keys stored in instance/space AI config (HKDF root)
  - BACKEND_MAIL_ENCRYPTION_KEY: encrypting email unsubscribe-link tokens
  - BACKEND_MAIL_ENCRYPTION_IV: encrypting email unsubscribe-link tokens
  - BACKEND_STORAGE_ENCRYPTION_KEY: encrypting attachment access tokens (local storage provider only)
  - BACKEND_STORAGE_ENCRYPTION_IV: encrypting attachment access tokens (local storage provider only)
  - BACKEND_ACCESS_TOKEN_ENCRYPTION_KEY: encrypting personal access tokens
  - BACKEND_ACCESS_TOKEN_ENCRYPTION_IV: encrypting personal access tokens
  - BACKEND_DATA_DB_URL_ENCRYPTION_KEY: encrypting BYODB database URLs
  - BACKEND_DATA_DB_URL_ENCRYPTION_IV: encrypting BYODB database URLs

Fine for a quick local try-out; for anything reachable from the network, set your own values.

[sandbox] SECURITY WARNING: SANDBOX_JWT_SECRET is not set — starting anyway on the PUBLICLY KNOWN former source default (it lives in the public git history, so anyone can forge execution tokens).

7.3 密钥生成与落配置

生成命令实测（每次执行结果不同，以下为实测样例）：

openssl rand -base64 32
openssl rand -hex 8
openssl rand -hex 8

arNqKGLeb0cJyMqPgWzVJK9Yno+V2j9dwntLdmZDJIY=
1f3dfd8b72471373
593baf48b1c66380

⚠️ 关键提醒（官方 Secrets and rotation 章节 + 告警行为一致）：

  1. 密钥缺失不阻断启动——回退值是公开的，任何人可伪造令牌/解密数据，仅限本机试用；
  2. 已用公开默认值运行过的实例，升级时先按启动告警打印的原值显式配置（保持旧会话/令牌可解密），再计划轮换；
  3. Compose 配置中密钥含 $ 字符时需转义（$$），否则会被变量展开吃掉。

八、认证与登录参数

8.1 密码登录开关：PASSWORD_LOGIN_DISABLED

属性值
默认值false
取值true 时禁用密码登录（官方注 OAuth/OIDC 仍可用）

实测（PASSWORD_LOGIN_DISABLED=true 后重启，密码登录接口整体消失）：

POST /api/auth/signin  => {"message":"Cannot POST /api/auth/signin","status":404,"code":"not_found"}
POST /api/auth/signup  => {"message":"Cannot POST /api/auth/signup","status":404,"code":"not_found"}

⚠️ 注意：是路由级移除（404）而非 403 拒绝。开启后管理员账号必须先配好 OAuth/OIDC，否则任何人都无法登录（含管理员）——生产慎用，或保留一个已登录会话再切换。

8.2 第三方登录组

变量默认值说明
SOCIAL_AUTH_PROVIDERS无启用列表，逗号分隔：github,google,oidc
BACKEND_GITHUB_CLIENT_ID / _SECRET无GitHub OAuth 应用凭据
BACKEND_GOOGLE_CLIENT_ID / _SECRET无Google OAuth 凭据
BACKEND_OIDC_CLIENT_ID / _SECRET / _CALLBACK_URL无通用 OIDC 凭据与回调地址

实测（未配置时启动日志告警，行为=功能关闭不报错）：

LEVEL 40 | GoogleSheetProvider | Google Sheets credentials not configured. Set BACKEND_GOOGLE_CLIENT_ID and BACKEND_GOOGLE_CLIENT_SECRET (shared with Google sign-in) environment variables.

8.3 登录验证码与防刷

变量默认值说明
BACKEND_SIGNIN_VERIFICATION_EXPIRES_IN10m验证码有效期（回退 BACKEND_EMAIL_CODE_EXPIRES_IN）
BACKEND_SIGNIN_VERIFICATION_MAX_ATTEMPTS5单验证码最大错误次数，超限作废
TURNSTILE_SITE_KEY / TURNSTILE_SECRET_KEY无Cloudflare Turnstile 人机校验
BACKEND_SIGNUP_VERIFICATION_CODE_RATE_LIMIT_SECONDS无注册验证码发送限流间隔（秒）
TEABLE_SSRF_PROTECTION_DISABLEfalse出站请求 SSRF 防护（禁回环/私网/链路本地地址），仅可信内网置 true
BACKEND_TRUST_PROXYloopback, linklocal, uniquelocal反向代理信任设置（影响审计日志中的客户端 IP）

实测（Turnstile 未配置的启动告警）：

LEVEL 40 | TurnstileService | Turnstile validation is disabled - missing site key or secret key

九、存储参数

9.1 存储后端：BACKEND_STORAGE_PROVIDER

属性值
默认值local
取值local / minio / s3 / aliyun
本地路径BACKEND_STORAGE_LOCAL_PATH 默认 .assets/uploads（相对应用目录，即挂载卷 /app/.assets/uploads）

实测（默认 local）：附件数据卷实测内容为 uploads/ 目录（上传后才产生子目录），公开桶/私有桶分别对应 URL 前缀 public / private（注册回显头像 URL 中的 /api/attachments/read/public/... 为证）。

9.2 桶与地址

变量默认值说明
BACKEND_STORAGE_PUBLIC_BUCKETpublic公开桶（头像等）
BACKEND_STORAGE_PRIVATE_BUCKETprivate私有桶（附件、应用文件、归档数据）
BACKEND_STORAGE_PUBLIC_URL无公开桶对外 URL 覆盖（可接 CDN）
BACKEND_STORAGE_PRIVATE_BUCKET_ENDPOINT无私有桶端点覆盖
STORAGE_PREFIX回退 PUBLIC_ORIGIN附件 URL 前缀

9.3 MinIO / S3 / 阿里云变量组（选配）

后端必配变量
MinIOBACKEND_STORAGE_MINIO_ENDPOINT、_PORT（默认 9000）、_USE_SSL（默认 false）、_ACCESS_KEY、_SECRET_KEY、_REGION（可选）、_INTERNAL_ENDPOINT / _INTERNAL_PORT（可选）
S3BACKEND_STORAGE_S3_REGION、_ENDPOINT、_ACCESS_KEY、_SECRET_KEY、_FORCE_PATH_STYLE（默认 false，端点不支持桶子域名时开启）、_INTERNAL_ENDPOINT / _INTERNAL_FORCE_PATH_STYLE / _MAX_SOCKETS（默认 100）
阿里云BACKEND_STORAGE_ALIYUN_* 组（同官方 env 页）
上传方式BACKEND_STORAGE_UPLOAD_METHOD 默认 put

💡 说明：切换存储后端只影响新上传文件，历史文件仍按原前缀访问；跨后端迁移需自行搬运对象并保持 key 一致。

十、邮件参数

官方已将邮件配置标记为 Deprecated，推荐走「管理面板 → 实例设置 → Email」可视化配置（通知邮箱与自动化邮箱分开配）；环境变量组仍可用作默认值：

变量默认值说明
BACKEND_MAIL_HOSTsmtp.teable.ai默认邮件服务器
BACKEND_MAIL_PORT465SMTP 端口
BACKEND_MAIL_SECUREtrueSSL/TLS
BACKEND_MAIL_SENDERnoreply.teable.ai发件地址
BACKEND_MAIL_SENDER_NAMETeable发件人显示名
BACKEND_MAIL_AUTH_USER / _PASS无SMTP 认证
BACKEND_MAIL_INVITE_USER_NAME_MAX_LENGTH / BACKEND_MAIL_INVITE_SPACE_NAME_MAX_LENGTH无（0=不截断）邀请邮件标题中名称截断长度

实测：未配置邮件时邀请/找回密码功能不可用（无告警阻断），按需在管理面板或环境变量二选一配置。

十一、资源限额参数

以下限额全部实测为官方默认值（未修改），生产按数据规模调整：

11.1 请求与上传

变量默认值说明
MAX_COPY_CELLS无（官方示例 50000）单次复制单元格上限
MAX_READ_ROWS无（官方示例 10000）单次读取行数上限
MAX_ATTACHMENT_UPLOAD_SIZE无（官方示例 2147483648，即 2GB）单附件上传字节上限

11.2 表结构限额（TABLE_LIMIT_*）

变量默认值
TABLE_LIMIT_TABLES_PER_BASE_MAX1000
TABLE_LIMIT_FIELDS_PER_TABLE_MAX500
TABLE_LIMIT_VIEWS_PER_TABLE_MAX100
TABLE_LIMIT_RECORDS_PER_TABLE_MAX无（不限，官方示例 1000000）
TABLE_LIMIT_RECORDS_PER_MUTATION_MAX20000
TABLE_LIMIT_SELECT_CHOICES_MAX1000
TABLE_LIMIT_FORMULA_MAX_LENGTH8192
TABLE_LIMIT_CELL_VALUE_MAX_BYTES262144
TABLE_LIMIT_RECORD_FIELDS_MAX_BYTES1048576
TABLE_LIMIT_VIEW_FILTER_ITEMS_MAX100
TABLE_LIMIT_VIEW_FILTER_DEPTH_MAX5
TABLE_LIMIT_VIEW_SORT_ITEMS_MAX20
TABLE_LIMIT_VIEW_GROUP_ITEMS_MAX3
TABLE_LIMIT_NAME_MAX_LENGTH100
TABLE_LIMIT_DESCRIPTION_MAX_LENGTH2000

💡 说明：默认限额对常规业务完全够用；TABLE_LIMIT_RECORDS_PER_TABLE_MAX 空值=不限行数，超大表场景建议显式设置并在架构上评估 PostgreSQL 单表规模。

十二、自动化 / AI / 运行时参数

12.1 自动化

变量默认值说明
AUTOMATION_MIN_SCHEDULED_MINUTES_INTERVAL10定时触发最小间隔（分钟），设大于 60 关闭分钟级调度
AUTOMATION_MIN_EMAIL_POLL_INTERVAL_MINUTES10邮件触发轮询最小间隔（分钟）

12.2 AI 与 App Builder（全功能形态才需要）

变量默认值说明
SANDBOX_PROVIDER无（示例 opensandbox）AI 会话沙箱提供方
TEABLE_INFRA_API_URL / TEABLE_INFRA_API_KEY无运行时平面入口（必须是公开入口地址）与共享密钥
TEABLE_INFRA_BUCKETteable-agentAI 工作区数据桶
SANDBOX_OPENSANDBOX_IMAGE无（示例 ghcr.io/teableio/teable-sandbox-agent，不带 tag）沙箱代理发布件前缀（应用自动追加版本 tag）
SANDBOX_OPENSANDBOX_RUNTIMEkubernetes沙箱引擎类型：kubernetes / docker（Docker 部署必须 docker）
SANDBOX_OPENSANDBOX_USE_SERVER_PROXYfalseDocker 本地模式建议 true
APP_DEPLOY_PROVIDervercelApp Builder 部署后端（全功能自托管用 docker-runtime）
SANDBOX_JWT_SECRET无（缺省回退公开值，见 7.2 告警）沙箱会话签名，全功能形态必填
SANDBOX_CPU / SANDBOX_MEMORY / SANDBOX_DISK2 / 4 / 15单沙箱 vCPU/内存 GiB/临时盘 GiB（管理面板设置优先）

实测（Standalone 形态）：内置沙箱组件随应用启动并监听 7070 端口（日志 [sandbox] listening on http://0.0.0.0:7070、[sandbox] Max concurrent: 10, Max queue: 2000），AI 会话/App Builder 的完整能力仍需运行时平面与许可。

12.3 遥测与分析

变量默认值说明
TELEMETRY_REPORT_DISABLEDfalse自托管遥测上报（含许可合规报告）；内网环境建议 true
OTEL_EXPORTER_OTLP_ENDPOINT无OpenTelemetry OTLP 上报端点
MICROSOFT_CLARITY_ID无微软 Clarity 分析

十三、功能开关参数

变量默认值说明
RECORD_HISTORY_DISABLEDfalse关闭记录历史
BACKEND_STORAGE_COLD_ARCHIVE_DISABLEDfalse停止历史数据定时归档（已归档数据仍可读）
PASSWORD_LOGIN_DISABLEDfalse见 8.1（路由级移除实测）
V2_TABLE_QUERY_OPS_ENABLEDfalse启用 Table Query Ops（管理面板对应页才有数据）；修改后需重启

十四、参数实测汇总表

#变量官方默认值实测方式实测结论
1TZ/TIMEZONEUTC注入 Asia/Shanghai 重建日志显示 System Time Zone: Asia/Shanghai ✅
2PORT3000启动日志观测Ready on http://localhost:3000 ✅
3NODE_ENVproduction启动日志观测NODE_ENV is production ✅
4LOG_LEVELinfo对比默认/debug 两实例日志默认无 20 级；debug 后出现 OpenApiDocs/WsGateway 20 级日志 ✅
5LOG_FORMATjson主实例日志观测pino JSON 行输出 ✅
6PRISMA_DATABASE_URL无（必填）注入死主机连接串启动期 getaddrinfo EAI_AGAIN 失败退出（Exited 1）✅
7BACKEND_CACHE_PROVIDERsqlite（官方）不配任何缓存变量启动实际自动拉起内置 Redis 并注入 URI，等效 redis ✅（重要差异）
8BACKEND_CACHE_REDIS_URI无（必填）注入外部 RedisFallbackQueueModule 跳过注册、无内置 Redis 启动 ✅
9BACKEND_PERFORMANCE_CACHE无未启用独立实例建议，按官方配置即可 ✅
10PUBLIC_ORIGIN无（必填）注册接口回显头像/链接 URL 前缀与配置一致 ✅
11BACKEND_SESSION_EXPIRES_IN7d登录 Cookie 观测服务端会话 7d；浏览器 Cookie 持久化 1 年（两层机制）✅
12BACKEND_SESSION_COOKIE_SECUREfalse默认观测Cookie 无 Secure 标记（HTTP 形态）✅
13BACKEND_JWT_EXPIRES_IN20d官方文档核对默认 20d ✅
14SECRET_KEY 等 13 密钥槽位公开内置值未配置启动打印完整 SECURITY WARNING 告警块，不阻断启动 ✅
15PASSWORD_LOGIN_DISABLEDfalse置 true 重启signin/signup 路由 404 移除 ✅
16OAuth/OIDC 组无未配置启动warn 级提示凭据未配置，功能关闭 ✅
17TURNSTILE_*无未配置启动warn 级提示校验关闭 ✅
18BACKEND_STORAGE_PROVIDERlocal上传/注册回显uploads/ 目录 + public/private 桶前缀 ✅
19BACKEND_MAIL_*smtp.teable.ai 组未配置邮件功能不可用，不阻断 ✅
20TABLE_LIMIT_*见 11.2官方文档核对默认值与官方一致 ✅
21SANDBOX_*（内置沙箱）见 12.2启动日志观测沙箱组件 7070 端口自启 + JWT 密钥告警 ✅
22TELEMETRY_REPORT_DISABLEDfalse官方文档核对内网部署建议置 true ✅

十五、常见问题（FAQ）

Q1：改了 .env/编排后参数没生效？

环境变量在服务创建时注入，restart 只重启进程不重读配置。实测改 PASSWORD_LOGIN_DISABLED 用 restart 后行为不变，重建后立即生效（路由 404）。解决：配置变更一律走编排重建（docker compose up -d），并观察启动日志确认新值（时区/端口/密钥告警块都会回显）。

Q2：启动日志刷一堆 SECURITY WARNING 是不是必须处理？

是密钥回退告警（见 7.2）：13 个密钥槽位缺失时用公开内置值兜底启动。本机试用可忽略；对外/多用户环境必须配置。已经用默认值运行过的实例，先按告警提示的原值显式写回配置保持数据可解密，再安排轮换。

Q3：不配 Redis 能不能跑？

能（实测见 5.3）：入口脚本自动拉起内置 Redis。但仅适合作试用——内置 Redis 不跨服务共享、无受控持久化，官方 Standalone 编排仍要求外置 Redis，多用户/自动化场景务必外置。

Q4：PUBLIC_ORIGIN 配错会怎样？

页面可用但所有对外链接（头像、邀请、分享）指向错误地址（实测头像 URL 前缀与配置一致）。改成真实访问地址后重建即可，已生成的旧链接按新配置重发。

Q5：数据库连接串写错为什么整服务起不来？

主库连接在启动期迁移阶段校验（实测 getaddrinfo EAI_AGAIN 后退出），这是有意设计——避免带病运行。按日志中的主机名/端口排障后重启即可。

Q6：PASSWORD_LOGIN_DISABLED=true 后把自己锁死了怎么办？

该开关是路由级移除（实测 404）。恢复：去掉该变量重建服务即可回退；已配置 OAuth/OIDC 的实例确认第三方登录可用后再开启此开关。

Q7：内置沙箱告警 SANDBOX_JWT_SECRET 怎么处理？

Standalone 形态不使用 AI 会话可忽略；启用 AI 能力时必须设置该密钥且与应用后端一致（实测告警建议 openssl rand -base64 32 生成后同时配到后端与沙箱）。

十六、参考链接

  1. 官方环境变量文档（本篇全部官方默认值来源）：https://help.teable.ai/en/deploy/env （查询日期 2026-10-18）
  2. 官方 Standalone 编排源文件（.env 结构来源）：https://github.com/teableio/teable/blob/develop/dockers/examples/standalone/docker-compose.yaml （查询日期 2026-10-18）
  3. 官方 Secrets and rotation 章节：https://help.teable.ai/en/deploy/env#secrets-and-rotation （查询日期 2026-10-18）
  4. 发布件对应仓库配置源码：apps/nestjs-backend/src/configs/（env.validation.schema.ts、cache.config.ts 等，teableio/teable@fef0615）
  5. 关联文档：《Teable Docker Compose 部署指南》（部署与编排实操）、《Teable 1.10 功能验证手册》（功能实测）、《Teable 1.10 介绍与选型指南》（版本与架构）