| 环境变量 | 描述 | 默认值 | 必填 | 示例 |
|---|---|---|---|---|
| 核心配置 | ||||
| PUBLIC_ORIGIN | 用于生成完整 URL 的公共源，必须设置为您的应用程序访问地址 | - | 是 | https://app.teable.ai |
| SECRET_KEY | 用于 JWT、会话和共享的根密钥，请生成强随机值 | - | 是 | openssl rand -base64 32 |
| BACKEND_JWT_SECRET | 签发登录、分享和插件 JWT 的密钥，未设置时回退到 SECRET_KEY | SECRET_KEY | - | openssl rand -base64 32 |
| BACKEND_SESSION_SECRET | 签发登录会话 Cookie 的密钥，未设置时回退到 SECRET_KEY | SECRET_KEY | - | openssl rand -base64 32 |
| BACKEND_STORAGE_ENCRYPTION_KEY | 附件访问令牌的加密密钥。BACKEND_STORAGE_PROVIDER 为 local 时必填 | - | 是 | 16 位随机字符串 |
| BACKEND_STORAGE_ENCRYPTION_IV | 与 BACKEND_STORAGE_ENCRYPTION_KEY 配对的加密 IV | - | 是 | 16 位随机字符串 |
| BACKEND_ACCESS_TOKEN_ENCRYPTION_KEY | 个人访问令牌的加密密钥 | - | 是 | 16 位随机字符串 |
| BACKEND_ACCESS_TOKEN_ENCRYPTION_IV | 与 BACKEND_ACCESS_TOKEN_ENCRYPTION_KEY 配对的加密 IV | - | 是 | 16 位随机字符串 |
| PORT | 应用程序运行的端口 | 3000 | - | 3000 |
| LOG_LEVEL | 日志级别，可选值：fatal、error、warn、info、debug、trace | info | - | debug |
| 存储配置 | ||||
| BACKEND_STORAGE_PROVIDER | 存储提供商，可选值：local、minio、s3、aliyun | local | - | s3 |
| BACKEND_STORAGE_LOCAL_PATH | 本地存储路径 | .assets/uploads | - | .assets/uploads |
| BACKEND_STORAGE_PUBLIC_BUCKET | public bucket 名称 | public | - | teable-public |
| BACKEND_STORAGE_PRIVATE_BUCKET | private bucket 名称，用于附件、应用文件、记录历史冷存储分片等需要保护的内容 | private | - | teable-private |
| BACKEND_STORAGE_PUBLIC_URL | public bucket 的公共访问 URL 覆盖（可选） | - | - | https://cdn.example.com |
| BACKEND_STORAGE_PRIVATE_BUCKET_ENDPOINT | private bucket 的 endpoint 覆盖（可选） | - | - | https://private-bucket.endpoint |
| BACKEND_STORAGE_S3_REGION | S3 云存储区域，当 BACKEND_STORAGE_PROVIDER 为 s3 时需要配置 | - | - | us-east-2 |
| BACKEND_STORAGE_S3_ENDPOINT | S3 云存储端点，当 BACKEND_STORAGE_PROVIDER 为 s3 时需要配置 | - | - | https://s3.us-east-2.amazonaws.com |
| BACKEND_STORAGE_S3_INTERNAL_ENDPOINT | S3 内网 endpoint（可选） | - | - | http://s3.internal |
| BACKEND_STORAGE_S3_FORCE_PATH_STYLE | 让浏览器访问 S3 时使用路径式 URL（endpoint/bucket/key）。当公网 endpoint 无法提供 bucket 子域名时启用。不能与 BACKEND_STORAGE_PRIVATE_BUCKET_ENDPOINT 同时使用 | false | - | true |
| BACKEND_STORAGE_S3_INTERNAL_FORCE_PATH_STYLE | 单独设置内网 S3 请求是否使用路径式访问。不设置时，如果公网和内网客户端共用 endpoint，则继承公网设置；使用独立内网 endpoint 时，默认使用虚拟主机式访问 | - | - | true |
| BACKEND_STORAGE_S3_ACCESS_KEY | S3 云存储访问密钥，当 BACKEND_STORAGE_PROVIDER 为 s3 时需要配置 | - | - | your_access_key |
| BACKEND_STORAGE_S3_SECRET_KEY | S3 云存储秘密密钥，当 BACKEND_STORAGE_PROVIDER 为 s3 时需要配置 | - | - | your_secret_key |
| BACKEND_STORAGE_S3_MAX_SOCKETS | S3 最大连接数（可选） | 100 | - | 100 |
| BACKEND_STORAGE_MINIO_ENDPOINT | Minio 存储端点 | - | - | minio.example.com |
| BACKEND_STORAGE_MINIO_PORT | Minio 端口 | 9000 | - | 443 |
| BACKEND_STORAGE_MINIO_USE_SSL | Minio 是否启用 SSL | false | - | true |
| BACKEND_STORAGE_MINIO_ACCESS_KEY | Minio 访问密钥 | - | - | access-key |
| BACKEND_STORAGE_MINIO_SECRET_KEY | Minio 秘密密钥 | - | - | secret-key |
| BACKEND_STORAGE_MINIO_INTERNAL_ENDPOINT | Minio 内网 endpoint（可选，不支持 HTTPS） | - | - | minio.internal |
| BACKEND_STORAGE_MINIO_INTERNAL_PORT | Minio 内网端口（可选） | 9000 | - | 9000 |
| BACKEND_STORAGE_MINIO_REGION | Minio region（可选） | - | - | us-east-1 |
| BACKEND_STORAGE_UPLOAD_METHOD | 上传方式 | put | - | put |
| STORAGE_PREFIX | 存储前缀，默认为 PUBLIC_ORIGIN | PUBLIC_ORIGIN | - | http://localhost:3000 |
| 缓存配置 | ||||
| BACKEND_CACHE_PROVIDER | 缓存提供商，可选值：sqlite、memory、redis | sqlite | - | redis |
| BACKEND_CACHE_REDIS_URI | 计算任务投递必需的 Redis 连接 URI；当 BACKEND_CACHE_PROVIDER 为 redis 时也用于缓存 | - | 是 | redis://default:teable@127.0.0.1:6379/0 |
| 性能缓存配置 | ||||
| BACKEND_PERFORMANCE_CACHE | 性能缓存 Redis URL，用于查询结果缓存，大幅提高多人协作场景下的处理效率，建议配置单独的 Redis 实例，不要与 BACKEND_CACHE_REDIS_URI 一样 | - | - | redis://default:teable@127.0.0.1:6379/0 |
| 认证配置 | ||||
| SOCIAL_AUTH_PROVIDERS | 社交认证提供商列表，多个提供商用逗号分隔 | - | - | github,google,oidc |
| BACKEND_GITHUB_CLIENT_ID | GitHub OAuth 客户端 ID | - | - | github_client_id |
| BACKEND_GITHUB_CLIENT_SECRET | GitHub OAuth 客户端密钥 | - | - | github_client_secret |
| BACKEND_GOOGLE_CLIENT_ID | Google OAuth 客户端 ID | - | - | google_client_id |
| BACKEND_GOOGLE_CLIENT_SECRET | Google OAuth 客户端密钥 | - | - | google_client_secret |
| BACKEND_OIDC_CLIENT_ID | OIDC 客户端 ID | - | - | google_client_id |
| BACKEND_OIDC_CLIENT_SECRET | OIDC 客户端密钥 | - | - | google_client_secret |
| BACKEND_OIDC_CALLBACK_URL | OIDC 回调 URL | - | - | https://app.teable.ai/api/auth/oidc/callback |
| 安全验证配置 | ||||
| TURNSTILE_SITE_KEY | Cloudflare Turnstile 站点密钥，用于身份验证验证 | - | - | 1x00000000000000000000AA |
| TURNSTILE_SECRET_KEY | Cloudflare Turnstile 秘密密钥，用于身份验证验证 | - | - | 1x0000000000000000000000000000000AA |
| TEABLE_SSRF_PROTECTION_DISABLED | 关闭出站请求保护，不再阻止回环、私有、链路本地和其他保留网络地址。仅当可信私有化部署必须访问内部接口时设为 true | false | - | true |
| BACKEND_SIGNUP_VERIFICATION_CODE_RATE_LIMIT_SECONDS | 注册验证邮箱发送频率间隔限制（秒） | - | - | 30 |
| BACKEND_TRUST_PROXY | 反向代理信任配置，用于在代理后识别客户端 IP，影响审计日志等安全记录。支持 true、false、代理跳数，或 IP/CIDR/preset 列表。为空时信任私有网络代理 | loopback, linklocal, uniquelocal | - | loopback, linklocal, uniquelocal |
| 邮件配置（已弃用 - 请使用管理面板 > 实例设置 > 邮箱） | ||||
| BACKEND_MAIL_HOST | 默认邮件服务器地址。推荐在管理面板 > 实例设置 > 邮箱中可视化配置通知邮箱和自动化邮箱 | smtp.teable.ai | - | smtp.gmail.com |
| BACKEND_MAIL_PORT | 默认邮件服务器端口 | 465 | - | 465 |
| BACKEND_MAIL_SECURE | 默认邮件服务是否使用 SSL/TLS | true | - | true |
| BACKEND_MAIL_SENDER | 默认发件人地址 | noreply.teable.ai | - | noreply@company.com |
| BACKEND_MAIL_SENDER_NAME | 默认发件人名称 | Teable | - | Teable |
| BACKEND_MAIL_AUTH_USER | 默认邮件服务器认证用户名 | - | - | username |
| BACKEND_MAIL_AUTH_PASS | 默认邮件服务器认证密码 | - | - | usertoken |
| BACKEND_MAIL_INVITE_USER_NAME_MAX_LENGTH | 邀请邮件主题中邀请人名称的最大长度。为空或 0 时不截断 | - | - | 32 |
| BACKEND_MAIL_INVITE_SPACE_NAME_MAX_LENGTH | 邀请邮件主题中空间或数据库名称的最大长度。为空或 0 时不截断 | - | - | 32 |
| 会话/JWT 配置 | ||||
| BACKEND_SESSION_EXPIRES_IN | 会话过期时间 | 7d | - | 7d |
| BACKEND_SESSION_COOKIE_SECURE | 是否启用会话 Cookie 安全保护，默认为 false | false | - | true |
| BACKEND_SESSION_ORIGIN_CHECK_ENABLED | 对使用浏览器会话 Cookie 的非安全 API 请求启用 Origin 与 Fetch Metadata 校验。仅在反向代理或 CDN 会保留这些请求头时启用 | false | - | false |
| BACKEND_JWT_EXPIRES_IN | JWT 过期时间 | 20d | - | 20d |
| BACKEND_RESET_PASSWORD_EMAIL_EXPIRES_IN | 重置密码邮件过期时间 | 30m | - | 30m |
| 资源限制 | ||||
| MAX_COPY_CELLS | 单次请求最大复制单元格数 | - | - | 50000 |
| MAX_READ_ROWS | 单次请求最大读取行数 | - | - | 10000 |
| MAX_ATTACHMENT_UPLOAD_SIZE | 附件上传最大大小（字节） | - | - | 2147483648 |
| TASK_MAX_FIELDS_PER_BATCH | 单次批量请求发送给模型的 AI 字段数量上限，取值会限制在 1 到 20 | 5 | - | 5 |
| TASK_MAX_CONCURRENCY | 每轮调度最多派发的待处理 AI 字段任务运行数，取值会限制在 1 到 20 | 5 | - | 5 |
| TABLE_LIMIT_FIELD_OPTIONS_MAX_BYTES | 字段选项序列化后的最大字节数 | 262144 | - | 262144 |
| TABLE_LIMIT_SELECT_CHOICES_MAX | 每个选择字段的最大选项数 | 1000 | - | 1000 |
| TABLE_LIMIT_SELECT_CHOICE_NAME_MAX_LENGTH | 选择项名称最大长度 | 1000 | - | 1000 |
| TABLE_LIMIT_SELECT_DEFAULT_VALUES_MAX | 选择字段默认值最大数量 | 100 | - | 100 |
| TABLE_LIMIT_CELL_VALUE_MAX_BYTES | 单元格值最大字节数 | 262144 | - | 262144 |
| TABLE_LIMIT_RECORD_FIELDS_MAX_BYTES | 记录字段数据序列化后的最大字节数 | 1048576 | - | 1048576 |
| TABLE_LIMIT_RECORDS_PER_MUTATION_MAX | 单次变更最大记录数 | 20000 | - | 20000 |
| TABLE_LIMIT_COMPUTED_CELL_VALUE_MAX_BYTES | 计算字段单元格值最大字节数 | 262144 | - | 262144 |
| TABLE_LIMIT_FORMULA_MAX_LENGTH | 公式最大长度 | 8192 | - | 8192 |
| TABLE_LIMIT_TABLES_PER_BASE_MAX | 每个数据库（Base）最大表数量 | 1000 | - | 1000 |
| TABLE_LIMIT_FIELDS_PER_TABLE_MAX | 每张表最大字段数 | 500 | - | 500 |
| TABLE_LIMIT_VIEWS_PER_TABLE_MAX | 每张表最大视图数 | 100 | - | 100 |
| TABLE_LIMIT_CREATE_TABLE_FIELDS_MAX | 创建表时允许的最大字段数 | 1000 | - | 1000 |
| TABLE_LIMIT_CREATE_TABLE_VIEWS_MAX | 创建表时允许的最大视图数 | 20 | - | 20 |
| TABLE_LIMIT_CREATE_TABLE_RECORDS_MAX | 创建表时允许的最大记录数 | 20000 | - | 20000 |
| TABLE_LIMIT_RECORDS_PER_TABLE_MAX | 每张表最大行数。为空时表示没有实例级行数上限 | - | - | 1000000 |
| TABLE_LIMIT_VIEW_FILTER_ITEMS_MAX | 单个视图最大筛选条件数 | 100 | - | 100 |
| TABLE_LIMIT_VIEW_FILTER_DEPTH_MAX | 单个视图最大嵌套筛选深度 | 5 | - | 5 |
| TABLE_LIMIT_VIEW_SORT_ITEMS_MAX | 单个视图最大排序条件数 | 20 | - | 20 |
| TABLE_LIMIT_VIEW_GROUP_ITEMS_MAX | 单个视图最大分组条件数 | 3 | - | 3 |
| TABLE_LIMIT_VIEW_OPTIONS_MAX_BYTES | 视图配置序列化后的最大字节数 | 262144 | - | 262144 |
| TABLE_LIMIT_NAME_MAX_LENGTH | 支持的表对象显示名称最大长度 | 100 | - | 100 |
| TABLE_LIMIT_DESCRIPTION_MAX_LENGTH | 支持的表对象描述最大长度 | 2000 | - | 2000 |
| AI 与 App Builder(运行平面接入) | ||||
| SANDBOX_PROVIDER | AI 会话的沙箱提供方;opensandbox 表示接入自部署运行平面 | - | - | opensandbox |
| TEABLE_INFRA_API_URL | 运行平面入口 URL —— 必须是公共入口(它负责把 /v1 分流给沙箱引擎),不能填内部服务地址 | - | - | https://infra.teable.example.com |
| TEABLE_INFRA_API_KEY | 与运行平面共享的 API 密钥 | - | - | your-infra-api-key |
| TEABLE_INFRA_BUCKET | AI 工作区数据面使用的存储桶 | teable-agent | - | teable-agent |
| SANDBOX_OPENSANDBOX_IMAGE | 沙箱 agent 镜像前缀(不带 tag) —— Teable 会拼上自身发布版本 tag,agent 永远与应用版本配对。中国部署使用阿里云镜像前缀 | - | - | ghcr.io/teableio/teable-sandbox-agent |
| SANDBOX_OPENSANDBOX_RUNTIME | 沙箱引擎运行时类型:kubernetes 或 docker。Docker 部署必须设为 docker | kubernetes | - | docker |
| SANDBOX_OPENSANDBOX_USE_SERVER_PROXY | 沙箱端点走引擎的路径代理而非按端口子域名(Docker local 模式使用) | false | - | true |
| APP_DEPLOY_PROVIDER | App Builder 的部署后端;全功能自部署使用 docker-runtime | vercel | - | docker-runtime |
| SANDBOX_JWT_SECRET | 沙箱会话签名密钥 —— 请按主机生成随机值，并在沙箱服务中使用相同的值 | - | 是 | 随机字符串 |
| SANDBOX_CPU | 每个沙箱的 vCPU 数(管理面板中的设置优先) | 2 | - | 2 |
| SANDBOX_MEMORY | 每个沙箱的内存(GiB,管理面板中的设置优先) | 4 | - | 4 |
| SANDBOX_DISK | 每个沙箱的临时磁盘(GiB,管理面板中的设置优先) | 15 | - | 15 |
| 功能开关 | ||||
| RECORD_HISTORY_DISABLED | 是否禁用记录历史，默认为 false | false | - | true |
| BACKEND_RECORD_HISTORY_COLD_DISABLED | 是否停止记录历史冷存储的定时迁移、合并和数据库缓冲区删除；读取仍会包含已迁移的历史 | false | - | true |
| PASSWORD_LOGIN_DISABLED | 是否禁用密码登录（OAuth 和 OIDC 仍然可用），默认为 false | false | - | true |
| 分析监控 | ||||
| MICROSOFT_CLARITY_ID | Microsoft Clarity 指标 ID，用于启用 Microsoft Clarity 分析 | - | - | your-metrics-id |
| OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry OTLP 端点 | - | - | http://jaeger:4317 |
| TELEMETRY_REPORT_DISABLED | 禁用自托管遥测上报，包括联网实例的许可合规上报 | false | - | true |
| 数据库配置 | ||||
| PRISMA_DATABASE_URL | 数据库连接 URL，必须配置 | - | 是 | postgresql://teable:teable@127.0.0.1:5432/teable |
| PUBLIC_DATABASE_PROXY | 对外可达的数据库地址（host:port），Base「数据库连接」面板生成的连接凭据会使用该地址；配置后即可从外部进行只读 SQL 访问 | - | - | db.example.com:42345 |
| PRISMA_TRANSACTION_TIMEOUT | 事务运行超时时间（毫秒），对于长时间运行的事务（如包含多个外键的批量更新）可以增加此值 | 5000 | - | 60000 |
| PRISMA_TRANSACTION_MAX_WAIT | 从连接池获取事务的最大等待时间（毫秒） | 2000 | - | 5000 |
| BIG_TRANSACTION_TIMEOUT | 大型内部事务的超时时间（毫秒），例如导出大型数据库 | 600000 | - | 1200000 |
密钥与轮换
上表中标注为密钥的每一项，都应该来自你自己的配置。服务在启动时会统一校验一次，但缺少密钥不会阻止启动：Teable 会回退到旧版本内置的默认值，在日志中列出缺失的变量，然后继续启动。这些内置值是公开的，任何人都可以据此伪造令牌或解密受其保护的数据。本地临时试用没问题，其他场景都不安全。 升级已有部署：此前没有配置这些变量的实例，一直在用旧的内置值，现在依然如此。启动警告会打印需要添加的配置块，照原样复制就能让现有会话、令牌和已加密数据继续可用；重启后再安排一次轮换。如果配置格式有要求，注意对值中的$ 做转义。
全新部署，直接生成新的随机值：
openssl rand -base64 32
*_ENCRYPTION_KEY 和 *_ENCRYPTION_IV 这类 16 位的槽位请改用 openssl rand -hex 8。
某个密钥被显式设置成公开的历史默认值时，启动日志同样会发出警告。实例会继续运行以保证数据可访问，但任何人都可以伪造令牌或解密受该密钥保护的数据，请尽快轮换。