Trac 1.6 配置参数详解

目标：逐 section 讲清 Trac 1.6 主配置文件 trac.ini 的全部配置段与关键参数（默认值均取自 1.6 初始化实测文件），并给出查看/修改/回滚的操作方式与生产配置模板。全部内容基于 Ubuntu 22.04 + Trac 1.6 实测环境（安装与运行见《Trac 1.6 安装指南（pip/tracd 形态）》，组件定位见《Trac 1.6 介绍与选型指南》）。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）；
Trac：1.6（pip 安装）；Python：3.10.12；
项目环境：/var/trac/myproject，配置文件 /var/trac/myproject/conf/trac.ini（初始化时同步生成对照样本 trac.ini.sample）；
服务：tracd 监听 8140，htdigest 认证（admin / q1w2e3r4，Realm TracRealm）；
参数清单来源：initenv 后的初始 trac.ini 全文实测（1.6 默认值），共 26 个 section。

二、前置条件

已按《Trac 1.6 安装指南（pip/tracd 形态）》完成安装并初始化至少一个项目环境；
知晓环境目录位置（trac-admin 与 trac.ini 均以环境目录为锚点）；
如需 Web 管理面板操作部分配置，admin 账号需具备 TRAC_ADMIN 权限（授予方法见《Trac 1.6 常用 CLI 命令详解》）。

三、参数查看与修改方式

3.1 三种修改途径

途径	命令/位置	适用场景
CLI	`trac-admin <env> config get/set/remove <section> <option>`	脚本化、远程运维
直接编辑	修改 `conf/trac.ini`	批量调整、模板下发
Web 面板	登录后进入 `Admin` 面板	日常点选（权限、组件、枚举值等）

3.2 config 子命令实测

trac-admin /var/trac/myproject config get project descr
trac-admin /var/trac/myproject config set project descr "Trac C1 测试描述"
trac-admin /var/trac/myproject config remove project descr

实测回显：

=== config get ===
My example project
=== config set ===
（成功时无输出）
=== set 后 get ===
Trac C1 测试描述
=== config remove ===
（成功时无输出）
=== remove 后 get（回默认值）===
My example project

要点：config set/remove 成功时静默；remove 删除 trac.ini 中的覆盖项后，读取值回落到内置默认值。

3.3 修改是否需要重启？（实测结论）

普通键值修改即时生效，无需重启 tracd。 实测过程：对运行中的 tracd 执行 config set project name "C1 重启验证名" 后不重启直接访问首页，页面标题立即变为新名称；将名称还原后同样无需重启即恢复。回显节选：

=== 1) 改配置 ===
（config set 无输出）
=== 2) 重启前访问（未重启进程）===
C1 重启验证名        ← 旧进程已读到新值

⚠️ 注意：自动重载覆盖 trac.ini 的键值改动；安装/卸载插件、升级版本后仍建议重启服务，让组件清单与新代码完整加载。

四、参数总览

trac.ini 默认共 26 个 section（1.6 初始文件实测），按功能分组如下：

分组	section	作用
全局核心	`[trac]`	数据库连接、权限策略链、Cookie、字符集等全局行为
项目外观	`[project]`、`[header_logo]`、`[mainnav]`、`[metanav]`	项目名/页脚/图标、导航菜单排序
日志	`[logging]`	日志类型/级别/文件/格式
组件与继承	`[inherit]`、（按需新增 `[components]`）	组件启停、多环境配置继承
工单	`[ticket]`、`[ticket-workflow]`	工单字段默认值/上限、状态机
通知	`[notification]`、`[notification-subscriber]`	SMTP 发信与订阅者规则
附件	`[attachment]`	附件大小与安全渲染
源码浏览	`[browser]`、`[changeset]`、`[revisionlog]`、`[versioncontrol]`、`[svn]`	仓库浏览/变更集/修订图/默认仓库类型
Wiki 与渲染	`[wiki]`、`[mimeviewer]`	Wiki 页面限制、语法着色
检索视图	`[timeline]`、`[query]`、`[report]`、`[search]`、`[roadmap]`、`[milestone]`	时间线/自定义查询/报表/搜索/路线图/里程碑
数据库	`[sqlite]`	SQLite 扩展加载
枚举值（不入 ini）	priority/severity/ticket_type/resolution/component/version/milestone	存于数据库，用 trac-admin 或 Web 面板管理

💡 技术拓展：trac.ini 是标准 INI 格式，布尔值写 enabled/disabled（也接受 true/false），列表用半角逗号分隔；[components] 段与插件相关，安装插件后才会出现。同类工具中 Redmine 用 YAML/数据库混合配置、MantisBT 用 config_inc.php，Trac 把全部可调项集中进单一 INI 是其运维上的显著优点。

五、核心参数分类详解

5.1 `[trac]` 全局核心

参数	默认值	说明
database	sqlite:db/trac.db	数据库连接串；PG/MySQL 需换连接串并装驱动
base_url	（空）	对外访问 URL；反向代理部署时必配
use_base_url_for_redirect	disabled	重定向是否强制走 base_url
default_charset	utf-8	缺省字符集
default_timezone / default_language / default_date_format / default_dateinfo_format	空 / 空 / 空 / relative	时区、界面语言、日期格式
default_handler	WikiModule	访问环境根路径时落到的处理器（默认进 Wiki 首页）
permission_policies	DefaultWikiPolicy,DefaultTicketPolicy,DefaultPermissionPolicy,LegacyAttachmentPolicy	权限策略链，自左向右判定；细粒度策略插件插到链首
permission_store	DefaultPermissionStore	权限存储后端
auth_cookie_lifetime / auth_cookie_path / auth_cookie_domain	0 / 空 / 空	会话 Cookie 生命周期（0=浏览器会话）、作用范围
anonymous_session_lifetime	90	匿名会话天数
ignore_auth_case	disabled	用户名大小写是否不敏感
secure_cookies	disabled	启用 HTTPS 后建议置 enabled
check_auth_ip	disabled	认证是否校验 IP
timeout	20	后端数据库连接超时（秒）
auto_reload	disabled	模板改动自动重载（开发调试用）
auto_preview_timeout	2.0	编辑页自动预览延迟
backup_dir	db	upgrade 前自动备份的存放子目录
debug_sql	disabled	日志中输出 SQL（排障用）
htdocs_location / jquery_location / jquery_ui_location / jquery_ui_theme_location	空	静态资源/ jQuery CDN 替换
show_email_addresses / show_full_names / never_obfuscate_mailto	disabled / enabled / disabled	邮箱与姓名展示策略
use_chunked_encoding	enabled	HTTP 分块传输
use_xsendfile / xsendfile_header	disabled / X-Sendfile	前端 Web 服务器接管文件下发
resizable_textareas / wiki_toolbars	enabled / enabled	编辑框体验项
request_filters	空	请求过滤组件挂载点

5.2 `[project]` 项目信息

参数	默认值	说明
name	（initenv 时确定，实测为 Trac 演示项目）	项目名，显示在页面标题
descr	My example project	项目描述
footer	Visit the Trac open source project at…	页脚 HTML
url	（空）	项目主页外链
admin / admin_trac_url	空 / .	管理员联系方式与面板链接
icon	common/trac.ico	浏览器标签图标

5.3 `[logging]` 日志

参数	默认值	说明
log_type	file	none/console/file/syslog/eventlog（Windows）
log_file	trac.log	相对环境目录 log/ 子目录
log_level	INFO	CRITIC/ERROR/WARN/INFO/DEBUG
log_format	（空）	空=默认格式；可自定义变量（如 `%(asctime)s %(levelname)s %(message)s`）

实测日志落盘于 /var/trac/myproject/log/trac.log，403 排障实录中的 HTTPForbidden 告警即来自该文件。

5.4 `[inherit]` 与按需新增的 `[components]`

[inherit]：htdocs_dir、plugins_dir、templates_dir 三个继承目录默认为空，用于多环境共享静态资源/插件/模板；
[components]：默认不出现在初始文件中，需要启停组件（含内置可选组件与插件）时新增。例如启用内置 Git 支持：

[components]
tracopt.versioncontrol.git.* = enabled

💡 说明：Trac 1.6 捆绑的可选 Git 组件默认关闭，SVN 绑定则随环境自动启用；插件组件的写法为 插件模块名.* = enabled。

5.5 `[ticket]` 工单字段

参数	默认值	说明
default_type / default_priority / default_resolution	defect / major / fixed	新建工单默认值
default_component / default_milestone / default_version / default_owner / default_cc / default_severity / default_keywords / default_summary / default_description	空（owner 为 `< default >`）	其余字段默认值
allowed_empty_fields	milestone,version	允许留空的枚举字段
max_comment_size / max_description_size / max_summary_size	262144（三项同）	内容上限（字节）
preserve_newlines	default	换行渲染策略
restrict_owner	disabled	负责人是否限定为已有工单者名单
workflow	ConfigurableTicketWorkflow	工作流引擎

5.6 `[ticket-workflow]` 默认状态机

初始文件实测的默认动作（状态 -> 状态，附所需权限）：

[ticket-workflow]
accept = new,assigned,accepted,reopened -> accepted
accept.operations = set_owner_to_self
accept.permissions = TICKET_MODIFY
create = <none> -> new
create.default = 1
create_and_assign = <none> -> assigned
create_and_assign.label = assign
create_and_assign.operations = may_set_owner
create_and_assign.permissions = TICKET_MODIFY
leave = * -> *
leave.default = 1
leave.operations = leave_status
reassign = new,assigned,accepted,reopened -> assigned
reassign.operations = set_owner
reassign.permissions = TICKET_MODIFY
reopen = closed -> reopened
reopen.operations = del_resolution
reopen.permissions = TICKET_CREATE
resolve = new,assigned,accepted,reopened -> closed
resolve.operations = set_resolution
resolve.permissions = TICKET_MODIFY

即：new → assigned → accepted → closed → reopened 五态循环，leave 为默认动作；.label 可本地化动作名，.permissions 控制谁可用该动作。

5.7 `[notification]` 与 `[notification-subscriber]` 通知

参数	默认值	说明
smtp_enabled	disabled	通知总开关
smtp_server / smtp_port	localhost / 25	SMTP 服务器
smtp_user / smtp_password	空 / 空	认证凭据
smtp_from / smtp_replyto / smtp_from_name	trac@localhost / trac@localhost / 空	发件人
smtp_always_cc / smtp_always_bcc	空	抄送/密送固定名单
smtp_default_domain	空	用户名补全为邮箱的默认域
email_sender	SmtpEmailSender	发信后端（另可用 SmtpEmailSender 之外的实现）
default_format.email	text/plain	邮件格式
mime_encoding	none	编码策略（中文建议 base64/qp）
ticket_subject_template	${prefix} #${ticket.id}: ${summary}	工单邮件主题模板
batch_subject_template	${prefix} Batch modify: ${tickets_descr}	批量修改邮件主题
ambiguous_char_width	single	东亚宽字符渲染（中文环境可设 double）
use_tls / use_public_cc / use_short_addr	disabled	传输与收件人策略
admit_domains / ignore_domains	空	邮箱域白/黑名单
message_id_hash	md5	Message-ID 哈希算法
sendmail_path	sendmail	sendmail 后端路径

[notification-subscriber] 默认三条订阅规则：always_notify_cc = CarbonCopySubscriber、always_notify_updater = TicketUpdaterSubscriber、always_notify_previous_updater = TicketPreviousUpdatersSubscriber（抄送者、当前修改者、前任修改者收信）。

5.8 `[attachment]` 附件

参数	默认值	说明
max_size	262144（256 KB）	单附件上限，生产建议放宽（如 10485760=10 MB）
max_zip_size	2097152（2 MB）	附件打包下载上限
render_unsafe_content	disabled	是否内联渲染潜在不安全内容（HTML/SVG 等）

5.9 源码浏览四件套与仓库配置

[browser]：downloadable_paths = /trunk,/branches/*,/tags/*（可下载路径）、hide_properties = svk:merge、color_scale = enabled（时间着色）、oldest_color = (136, 136, 255)、newest_color = (255, 136, 136)、intermediate_point（中间色位）、wiki_properties = trac:description、oneliner_properties = trac:summary、render_unsafe_content = disabled；
[changeset]：max_diff_bytes = 10000000、max_diff_files = 0（0=不限文件数）、wiki_format_messages = enabled（提交说明用 Wiki 渲染）；
[revisionlog]：default_log_limit = 100、graph_colors = #cc0,#0c0,#0cc,#00c,#c0c,#c00（修订图配色）；
[versioncontrol]：default_repository_type = svn、allowed_repository_dir_prefixes = （仓库目录白名单前缀）；
[svn]：authz_file = （SVN authz 细粒度授权文件路径）、authz_module_name = 。

5.10 `[wiki]` 与 `[mimeviewer]`

[wiki]：max_size = 262144（单页上限）、default_edit_area_height = 20（编辑框行数）、split_page_names = disabled（CamelCase 是否拆词显示）、ignore_missing_pages = disabled（不存在页链接是否静默）、render_unsafe_content = disabled、safe_schemes = cvs,file,ftp,git,irc,http,https,news,sftp,smb,ssh,svn,svn+ssh（允许的外链协议）、safe_origins = data:；
[mimeviewer]：max_preview_size = 262144、tab_width = 8、mime_map = text/x-dylan:dylan,text/x-idl:ice,text/x-ada:ads:adb（扩展名到 MIME 补充映射）、mime_map_patterns = text/plain:README(?!\.rst)|INSTALL(?!\.rst)|COPYING.*、treat_as_binary = application/octet-stream,application/pdf,application/postscript,application/msword,application/rtf。

5.11 检索与视图类

[timeline]：default_daysback = 30、max_daysback = 90（时间线默认/最大回溯天数）、abbreviated_messages = enabled、changeset_show_files = 0（提交事件是否列文件）、changeset_collapse_events / changeset_long_messages = disabled、newticket_formatter = oneliner、ticket_show_component / ticket_show_details = disabled / enabled；
[query]：default_query = status!=closed&owner=$USER、default_anonymous_query = status!=closed&cc~=$USER（自定义查询默认条件）、items_per_page = 100、ticketlink_query = ?status=!closed（#1 快捷链接的过滤条件）；
[report]：items_per_page = 100、items_per_page_rss = 0（0=RSS 不分页）；
[search]：min_query_length = 3（最短搜索词长，中文检索常降到 1~2）、default_disabled_filters = （默认停用的搜索域）；
[roadmap]：stats_provider = DefaultTicketGroupStatsProvider（进度统计器）；
[milestone]：default_group_by = component（路线图分组维度）、default_retarget_to = （里程碑完成时工单默认改挂目标）、stats_provider = DefaultTicketGroupStatsProvider。

5.12 导航与外观

[mainnav]：八项主导航排序（wiki.order=1.0、timeline.order=2.0、roadmap.order=3.0、browser.order=4.0、tickets.order=5.0、newticket.order=6.0、search.order=7.0、admin.order=8.0）；
[metanav]：辅助导航排序（login=1.0、logout=2.0、prefs=3.0、help=4.0、about=5.0）；
[header_logo]：src = site/your_project_logo.png（放环境 htdocs/site/ 下）、alt/height/width/link。

5.13 `[sqlite]` 与其他

[sqlite]：extensions = （SQLite 扩展 .so 加载列表，默认空）；
枚举值（优先级/严重级/类型/解决结果/组件/版本/里程碑）不在 trac.ini，存于数据库：priority 默认 blocker/critical/major/minor/trivial，ticket_type 默认 defect/enhancement/task，severity 默认为空——均可用 trac-admin 的同名子命令或 Web 面板维护（实测回显见《Trac 1.6 常用 CLI 命令详解》）。

六、生产配置模板

适用场景：小中型团队（≤20 人）、2C4G 内存 / 40GB 磁盘单机、SVN+Git 双仓库、SQLite 存储、tracd+systemd 托管。以下为在初始 trac.ini 之上的增量模板（未列出项保持默认）：

[project]
name = 核心业务平台
descr = 研发一组的工单与文档中枢
footer = 内部系统 · 仅限授权访问

[trac]
base_url = https://trac.example.com/myproject   # 反向代理后必须
secure_cookies = enabled                        # 全站 HTTPS 时启用
default_timezone = Asia/Shanghai
default_language = zh_CN
permission_policies = DefaultWikiPolicy,DefaultTicketPolicy,DefaultPermissionPolicy,LegacyAttachmentPolicy

[logging]
log_type = file
log_level = INFO                                # 排障期临时改 DEBUG
log_file = trac.log

[attachment]
max_size = 10485760                             # 10 MB
max_zip_size = 20971520                         # 20 MB
render_unsafe_content = disabled

[ticket]
default_priority = major
default_type = task
restrict_owner = enabled                        # 负责人仅可从成员中选

[notification]
smtp_enabled = enabled
smtp_server = smtp.example.com
smtp_port = 587
smtp_user = trac-bot@example.com                # 凭据建议由部署系统注入
smtp_password = ${SMTP_PASSWORD}
smtp_from = trac-bot@example.com
smtp_replyto = dev-lead@example.com
smtp_default_domain = example.com               # 短用户名自动补域
ambiguous_char_width = double                   # 中文宽字符对齐
mime_encoding = base64

[query]
default_query = status!=closed&owner=$USER
items_per_page = 100

[search]
min_query_length = 2                            # 中文短词可搜

[timeline]
default_daysback = 30
max_daysback = 90

[components]
tracopt.versioncontrol.git.* = enabled          # 启用内置 Git 支持

[versioncontrol]
default_repository_type = git

⚠️ 注意：${SMTP_PASSWORD} 为环境注入占位，请勿把真实口令写入 trac.ini 并提交到代码库；修改后普通键值即时生效（见 3.3），改完用 trac-admin <env> config get 复核。

七、常见问题（FAQ）

Q1：改了 trac.ini 必须重启 tracd 吗？ 普通键值不用——运行中进程会自动重载（3.3 实测）；但安装/卸载插件、更换数据库驱动后建议 systemctl restart tracd。

Q2：config remove 把配置删了会坏吗？ 不会。remove 只删除 ini 中的覆盖项，读取时回落到内置默认值（3.2 实测：descr 删除后回到 My example project）。

Q3：想给多个项目共用一份配置？ 用 [inherit] 指向共享模板目录，或各环境定期模板化下发；Trac 没有原生的"全局 ini 合并"，[inherit] 仅覆盖三类资源目录。

Q4：附件默认只有 256 KB？ 是的，[attachment] max_size 默认 262144，生产环境按需调大即可（模板中已给 10 MB 示例）。

Q5：中文邮件主题乱码？ 设置 [notification] mime_encoding = base64（或 qp），并将 ambiguous_char_width 设为 double 改善宽字符排版。

Q6：数据库能从 SQLite 换 PostgreSQL 吗？ 可以：装驱动后用新连接串建环境并迁移数据（1.6 自带 convert_db 子命令可转换库后端），[trac] database 同步修改；大规模迁移建议走 hotcopy + 全新环境导入。

八、参考链接

官方配置文档 TracIni：https://trac.edgewall.org/wiki/TracIni（查询日期 2026-10-31）
官方工作流文档 TracWorkflow：https://trac.edgewall.org/wiki/TracWorkflow（查询日期 2026-10-31）
官方通知文档 TracNotification：https://trac.edgewall.org/wiki/TracNotification（查询日期 2026-10-31）
官方权限文档 TracPermissions：https://trac.edgewall.org/wiki/TracPermissions（查询日期 2026-10-31）
官方日志文档 TracLogging：https://trac.edgewall.org/wiki/TracLogging（查询日期 2026-10-31）
站内相关：《Trac 1.6 介绍与选型指南》（www.quzuo.net/document/JXaGjcwsQwjr）、《Trac 1.6 安装指南（pip/tracd 形态）》（www.quzuo.net/document/fQ9S36Lh2gmw）、《Trac 1.6 常用 CLI 命令详解》（www.quzuo.net/document/A6zMBWSVIxRL）

Trac 1.6 配置参数详解

Trac 1.6 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 三种修改途径

3.2 config 子命令实测

3.3 修改是否需要重启？（实测结论）

四、参数总览

五、核心参数分类详解

5.1 [trac] 全局核心

5.2 [project] 项目信息

5.3 [logging] 日志

5.4 [inherit] 与按需新增的 [components]

5.5 [ticket] 工单字段

5.6 [ticket-workflow] 默认状态机

5.7 [notification] 与 [notification-subscriber] 通知

5.8 [attachment] 附件

5.9 源码浏览四件套与仓库配置

5.10 [wiki] 与 [mimeviewer]

5.11 检索与视图类

5.12 导航与外观

5.13 [sqlite] 与其他

六、生产配置模板

七、常见问题（FAQ）

八、参考链接

5.1 `[trac]` 全局核心

5.2 `[project]` 项目信息

5.3 `[logging]` 日志

5.4 `[inherit]` 与按需新增的 `[components]`

5.5 `[ticket]` 工单字段

5.6 `[ticket-workflow]` 默认状态机

5.7 `[notification]` 与 `[notification-subscriber]` 通知

5.8 `[attachment]` 附件

5.10 `[wiki]` 与 `[mimeviewer]`

5.13 `[sqlite]` 与其他