Tryton 8.2 配置参数详解

目标：逐项讲清 trytond 8.2.1 主配置文件 trytond.conf 的全部配置节与参数——加载机制、优先级（默认值 < 环境变量 < 配置文件）、13 个配置节逐参数表（含源码权威默认值）、生产示例与生效验证。默认值取自 trytond 8.2.1 源码 trytond/config.py，实测基于 Ubuntu 22.04 + trytond 8.2.1。

一、配置加载机制

trytond 的配置由 trytond/config.py 中的 TrytonConfigParser 管理，启动时按固定顺序加载三类来源：

内置默认值：进程 import 时写入全部默认值；
环境变量：紧接着扫描 TRYTOND_ 前缀的环境变量覆盖默认值；
配置文件：最后读取 -c 参数（或 TRYTOND_CONFIG 环境变量）指定的 ini 文件，覆盖前两者。

⚠️ 关键结论（与多数软件相反）：trytond 中配置文件的优先级高于环境变量。同一参数若配置文件里写了，环境变量注入会被覆盖；只有配置文件未涉及的键，环境变量才生效。实测验证：

# /etc/tryton/trytond.conf 中 [session] timeout = 600
export TRYTOND_REQUEST__MAX_SIZE=9999999
export TRYTOND_SESSION__TIMEOUT=900
python3 -c "
from trytond.config import config
config.update_etc('/etc/tryton/trytond.conf')
print('request.max_size =', config.getint('request','max_size'))
print('session.timeout  =', config.getint('session','timeout'))
"

实测输出：

request.max_size = 9999999
session.timeout  = 600

max_size 配置文件未设置 → 取环境变量 9999999；timeout 配置文件已设 600 → 环境变量的 900 被覆盖。

1.1 环境变量注入格式

规则：TRYTOND_<节名>__<键名>（节名与键名之间双下划线，一律大写，加载时自动转小写）。例如：

export TRYTOND_DATABASE__URI='postgresql://tryton:q1w2e3r4@localhost:5432/trytondb'
export TRYTOND_WEB__LISTEN='0.0.0.0:8000'

另外有三个不走双下划线规则的专用变量：

变量	作用
`TRYTOND_CONFIG`	指定配置文件路径（等价于 `-c`）
`TRYTOND_DATABASE_URI`	整体指定数据库连接串（等价 `[database] uri` 的默认值来源）
`TRYTONPASSFILE`	trytond-admin 读 admin 密码的文件路径（免交互）
`TRYTOND_DATABASE_NAMES`	WSGI 入口预初始化的数据库名（gunicorn 托管时必须，详见安装篇 FAQ）

1.2 配置文件格式与多文件

标准 ini 格式，注释用 # 或 ;。-c 可传多个文件（trytond -c base.conf -c local.conf），后读的文件覆盖先读的同名字段。默认查找路径为 TRYTOND_CONFIG 环境变量，未设置时 trytond 不带配置文件也能跑（全默认值，数据库为 sqlite）。

二、[web] HTTP 服务节

控制内建 Werkzeug 服务的监听与静态资源。

参数	默认值	说明
`listen`	`localhost:8000`	监听地址，逗号分隔可写多个。对外服务必须改 `0.0.0.0:8000`
`root_path`	`/`	URL 前缀，反向代理挂子路径时设置
`root`	`~/www`（安装用户家目录下）	Web 客户端（tryton-sao）静态文件目录
`num_proxies`	`0`	前置代理层数，影响 X-Forwarded-For 取值
`cache_timeout`	`43200`（12 小时，秒）	静态资源 Cache-Control 时长
`hostname`	无	强制 URL 生成时使用的主机名
`cors`	无	允许的跨域来源，逗号分隔

三、[database] 数据库节

Tryton 8.x 仅支持 PostgreSQL，本节是必填核心。

参数	默认值	说明
`uri`	`sqlite://`（或 `TRYTOND_DATABASE_URI`）	连接串 `postgresql://用户:密码@主机:端口/库名`，生产必配
`path`	`~/db`	附件等文件的落盘根目录（配合 `[attachment] filestore`）
`list`	`True`	是否允许客户端列出服务器上的数据库；生产可设 `False` 隐藏
`retry`	`5`	数据库操作失败重试次数
`language`	`en`	新库初始化的默认语言
`timeout`	`1800`（秒）	事务空闲超时，超时连接被回收
`subquery_threshold`	`1000`	IN 子查询转 JOIN 的阈值，影响大表查询计划
`maxconn`	无（按 psycopg-pool 默认）	单进程连接池上限
`minconn`	无	连接池保留下限
`default_name`	无	客户端未指定库时的默认库名
`unaccent_function`	无	自定义去重音函数名（搜索用）

四、[request] 请求节

参数	默认值	说明
`max_size`	`2097152`（2MB）	匿名请求体上限
`max_size_authenticated`	`2147483648`（2GB）	登录后请求体上限（附件导入走此项）
`timeout`	`60`（秒）	单请求处理超时
`records_limit`	无（不限制）	单次读操作返回记录数上限，防全表拉取

五、[cache] 缓存节

trytond 用内存缓存加速模型元数据与记录读取，单位均为条数/秒。

参数	默认值	说明
`transaction`	`10`	每事务缓存的事务数
`model`	`200`	模型定义缓存条数
`record`	`2000`	记录缓存条数（业务量大可调至 5000+）
`field`	`100`	字段元数据缓存条数
`default`	`1024`	未单独指定的缓存池默认容量
`ir.message`	`10240`	消息缓存
`ir.translation`	`10240`	翻译缓存（多语言环境重点调此项）
`clean_timeout`	`300`（秒）	缓存清理周期
`select_timeout`	`60`（秒）	缓存失效通知的轮询间隔
`class`	无	自定义缓存后端类（如接 Redis 时指定）

六、[queue] 异步任务节

参数	默认值	说明
`worker`	`False`	是否在本进程内跑队列 worker；生产建议用独立 `trytond-worker`
`batch_size`	无	单批处理任务数
`clean_days`	无	已完成任务保留天数

七、[ssl] TLS 节

参数	默认值	说明
`privatekey`	无	TLS 私钥路径，设置后内建服务直接提供 HTTPS
`certificate`	无	TLS 证书路径

生产更常见的是用 Nginx 终止 TLS 再反代到 8000 端口，此时本节点留空。

八、[email] 邮件节

参数	默认值	说明
`uri`	`smtp://localhost:25`	SMTP 连接串，支持 `smtps://`、`smtp+ssl://` 等
`from`	安装用户名（root 安装即 `root`）	系统邮件发件人地址
`retry`	无	发送失败重试次数

九、[session] 会话节

参数	默认值	说明
`authentications`	`password`	启用的认证方式列表（可挂 ldap 等模块扩展）
`max_age`	`2592000`（30 天，秒）	会话 token 最长寿命
`timeout`	`300`（秒）	会话空闲超时
`max_attempt`	`5`	单账号连续失败登录次数上限，超过锁定
`max_attempt_ip_network`	`300`	同网段失败次数上限（防分布式爆破）
`ip_network_4`	`32`	IPv4 网段掩码（配合上条统计）
`ip_network_6`	`56`	IPv6 网段掩码
`cookie_domain`	无	会话 Cookie 的作用域

十、[password] 密码策略节

参数	默认值	说明
`length`	`8`	用户密码最小长度
`reset_timeout`	`86400`（24 小时，秒）	密码重置链接有效期
`forbidden`	无	禁用密码清单文件路径（每行一个弱密码）

十一、[bus] 实时推送节

参数	默认值	说明
`allow_subscribe`	`False`	是否允许客户端订阅总线消息
`long_polling_timeout`	`300`（秒）	长轮询保持时长
`cache_timeout`	`300`（秒）	总线消息缓存时长
`select_timeout`	`5`（秒）	内部轮询间隔
`url_host`	无	总线服务对外主机名（独立部署时）
`class`	无	自定义总线后端类

十二、[report] / [html] / [attachment] 节

节.参数	默认值	说明
`html.license_key`	无	TinyMCE 商业许可 key（富文本编辑器，开源用法可空）
`attachment.filestore`	无（默认入库）	设为 `True` 后附件存 `[database] path` 目录而非数据库
`attachment.store_prefix`	无	文件存储路径前缀（多实例共享存储时区分）
`attachment.retention_days`	无	附件保留天数（配合清理任务）
`[report]`	—	历史报表服务节，8.2 内核已不消费，留作兼容

十三、生产参考配置

综合以上逐项说明，一套中等规模生产配置示例（与本专栏安装篇实际使用的配置一致）：

[database]
uri = postgresql://tryton:q1w2e3r4@localhost:5432/trytondb
path = /var/lib/tryton

[web]
listen = 0.0.0.0:8000
root = /var/lib/tryton/www

[cache]
model = 500
record = 500
field = 500

[session]
timeout = 600

要点解读：uri 指向 PostgreSQL；listen 放开对外监听；缓存三项按默认 model=200/record=2000/field=100 的基础上调 model 与 field；session.timeout 由 300 秒放宽到 600 秒，避免频繁重新登录。

十四、配置生效验证

改完配置后，用 Python 直接读解析器确认生效值（路径换成实际配置文件）：

python3 -c "
from trytond.config import config
config.update_etc('/etc/tryton/trytond.conf')
print('uri =', config.get('database','uri'))
print('listen =', config.get('web','listen'))
print('session.timeout =', config.getint('session','timeout'))
"

实测输出：

uri = postgresql://tryton:q1w2e3r4@localhost:5432/trytondb
listen = 0.0.0.0:8000
session.timeout = 600

与配置文件写入值一致，配置加载正常。启动 trytond 时日志也会打印 using /etc/tryton/trytond.conf as configuration files，可据此确认加载了正确的文件。

十五、常见问题

Q1：改了配置不生效？

按优先级排查：① 确认启动命令带了 -c /etc/tryton/trytond.conf（不带则全用默认值）；② 确认该键没有被配置文件覆盖掉你的环境变量（配置文件优先级更高，见第一节）；③ ini 节名拼写必须与本文一致（如 [database] 不是 [databases]）。

Q2：环境变量 TRYTOND_SESSION_TIMEOUT=900（单下划线）为什么不生效？

节名与键名之间必须是双下划线：TRYTOND_SESSION__TIMEOUT。单下划线写法解析不出节名会被静默忽略（源码中 split('__', 1) 失败即跳过）。

Q3：SQLite 能用于生产吗？

不能。uri 默认的 sqlite:// 仅供开发体验，官方明确生产仅支持 PostgreSQL。

十六、参考链接

官方文档 - trytond 配置：https://docs.tryton.org/projects/server/en/latest/topics/configuration.html （查询日期 2026-10-25）
trytond 源码（config.py 权威默认值）：https://github.com/Tryton/trytond （查询日期 2026-10-25）