Tableau Server 2022.3 tsm 配置参数详解

目标：系统梳理 Tableau Server 2022.3（内部版本 20223.24.0423.1447）的 tsm 配置体系，覆盖配置键的查看与修改、pending-changes 变更应用与回滚机制、动态键与重启键的差异、settings 导入导出以及 environment.bash 初始化参数。全文命令与回显在 CentOS 8（x86_64）实测通过，示例主机名 tableau-01。

一、配置体系总览

Tableau Server 的配置分四个层面，理解分层是正确使用 tsm 的前提：

关键约束：

• 任何 tsm configuration set 都不会立即生效，必须 tsm pending-changes list 预览后 tsm pending-changes apply 落地
• apply 会按拓扑重配服务：仅动态键变更时各服务平滑重载；含拓扑或非动态键变更时服务会短暂停机重启
• 身份存储（identityStore）与注册信息必须在 tsm initialize 之前设置

二、查看配置

2.1 tsm configuration get 读取单个键

语法：tsm configuration get -k <key>。实测读取三个网关键：

tsm configuration get -k gateway.public.port

80

tsm configuration get -k gateway.public.host

tableau-01

tsm configuration get -k gateway.timeout

7200

• gateway.public.port：对外网关端口（默认 80）
• gateway.public.host：对外主机名，初始化时自动取服务器主机名
• gateway.timeout：网关到后端的请求超时（秒），导入大工作簿报网关超时可调大

2.2 tsm configuration list-dynamic-keys 列出动态键

动态键支持在不停机的情况下应用（服务平滑重载）。实测列出部分：

tsm configuration list-dynamic-keys

gateway.log.level
tsm.controlapp.log.level
backup.zstd.thread_count
tdsservice.log.level
backgrounder.log.level
filestore.log.level
basefilepath.backuprestore
tabadmincontroller.auth.expiration.minutes
vizportal.log.level
vizqlserver.log.level
tsm.log.level
basefilepath.site_export.exports
dataserver.log.level
clustercontroller.log.level
tomcatcontainer.log.level
vizdatanativeservice.log.level
basefilepath.site_import.exports

该清单是判断一次变更"是否需要停机"的依据：若 pending 变更里的键全部在动态清单内，apply 期间 Tableau Server 业务入口保持可用（TSM 会平滑重载相关服务）。

💡 未收录在动态清单中的键（如大多数 wgserver.*、maestro.* 参数）apply 时会触发服务重启，需安排变更窗口。

三、常用配置键详解

按功能域分组，均为实测可读写的键。get 列为实测当前值。

3.1 网关与访问

3.2 日志级别

各服务日志级别键统一为 <服务>.log.level，均为动态键，支持在线调整：

3.3 备份与导出路径

3.4 认证与会话

3.5 性能相关

四、修改配置与生效

4.1 set → list → apply 标准流程

以调整 TSM 会话过期为例（该键为动态键，变更无需重启）。第一步设置：

tsm configuration set -k tabadmincontroller.auth.expiration.minutes -v 240

set 无回显即写入成功。第二步预览变更：

tsm pending-changes list

If all changes are marked "(NO RESTART NEEDED)", changes are applied with no impact to Tableau Server availability.
Configuration
Key: tabadmincontroller.auth.expiration.minutes (NO RESTART NEEDED)
                               New Value: 240
Topology
There are no pending topology changes.
These changes will not require a server restart.

list 输出会逐键标注是否需要重启：动态键标 (NO RESTART NEEDED)，结尾给出整体结论 These changes will not require a server restart.。若变更含非动态键或拓扑项，则不再有该标注、apply 时会重启服务器——据此安排变更窗口。

第三步应用：

tsm pending-changes apply --ignore-prompt

--ignore-prompt 跳过交互确认，适合脚本化。apply 是异步 Job，CLI 实时输出进度直至 Successfully deployed nodes with updated configuration and topology version.（仅动态键变更期间服务平滑重载，业务不中断）。

4.2 discard 回滚未应用变更

set 之后反悔、或误设参数尚未 apply 时，直接丢弃待应用变更即可，不影响运行中的服务：

tsm pending-changes discard

Pending changes discarded.

丢弃后用 get 验证，当前值仍是原值 120（未受 set 影响）：

tsm configuration get -k tabadmincontroller.auth.expiration.minutes

120

回滚已 apply 的配置没有 discard 可用——重新 set 回原值再 apply 一次。

4.3 动态键与重启键的行为差异

• 仅含动态键的变更：apply 时各服务平滑重载，网关入口不中断
• 含非动态键（或拓扑变更）：apply 前会提示重启，--ignore-prompt 直接重启，业务短暂中断
• 判断方法见 2.2：变更涉及的键逐一对照 tsm configuration list-dynamic-keys

五、settings 导入导出

5.1 import 导入配置实体

tsm settings import 是设置身份存储等 configEntities 的唯一 CLI 途径（本版本无 tsm user-identity-store set 子命令）。以本地身份存储为例：

cat > /opt/identity.json << 'EOF'
{
  "configEntities": {
    "identityStore": {
      "_type": "identityStoreType",
      "type": "local"
    }
  }
}
EOF

tsm settings import -f /opt/identity.json

Configuration file read from /opt/identity.json. The configuration file does not include the runas username and password. After importing, these values must be set explicitly.

导入后进入 pending 状态，apply 落地：

tsm pending-changes apply --ignore-prompt

进度节选（实测首尾）：

Job id is '0', timeout is 30 minutes.
9% - Validating that there are no pending changes.
100% - Successfully deployed nodes with updated configuration and topology version.

验证：

tsm user-identity-store list

Type: local

💡 提示 "does not include the runas username and password" 属正常提醒：runas 账户在 initialize-tsm 时由 -a 参数指定，导入文件无需包含。

5.2 export 导出配置

tsm settings export -f /opt/tableau-settings.json

导出文件包含当前活动配置与拓扑，可用于同版本环境的配置基线留存。注意：导出不含许可信息，且包含机密字段时需妥善保管文件权限。

5.3 clone 克隆配置

tsm settings clone -d /opt/clone-output-dir

clone 会导出配置、机密与拓扑的完整副本（含密钥材料），用于新节点部署或灾难恢复场景，文件务必加密保管。

六、environment.bash 初始化参数

initialize-tsm 写入的初始化参数固化在 /etc/opt/tableau/tableau_server/environment.bash，实测全文：

cat /etc/opt/tableau/tableau_server/environment.bash

# Tableau Server global initialization parameters
TABLEAU_TSIG_DATA_DIR="/var/opt/tableau/tableau_server"
TABLEAU_SERVER_DATA_DIR="/var/opt/tableau/tableau_server"
TABLEAU_SERVER_CONFIG_NAME="tabsvc"
TABLEAU_SERVER_DATA_DIR_VERSION="20223.24.0423.1447"
TABLEAU_SERVER_UNPRIVILEGED_USERNAME="tableau"
TABLEAU_SERVER_TSM_AUTHORIZED_GROUPNAME="tsmadmin"
TABLEAU_SERVER_USERS_AND_GROUPS_CREATED="1"

⚠️ 该文件为 initialize-tsm 的产物，属初始化层参数，日常运维不要手工编辑；数据目录、账户等变更应通过重新引导或升级流程完成。

七、常见问题

7.1 set 之后参数没生效

tsm configuration set 只写入待应用变更，必须执行 tsm pending-changes apply --ignore-prompt 才落地。set 后先用 tsm configuration get 确认当前值，再用 tsm pending-changes list 区分"已设未应用"与"已应用"。

7.2 apply 提示将重启服务器，能否不停机

取决于变更键是否全部为动态键（见 2.2）。全部动态键 → 平滑重载不停机；含非动态键 → 必然重启，只能安排窗口。

7.3 tsm licenses atr-configuration get 报 Missing required option

atr-configuration 是 set 型配置（tsm licenses atr-configuration set --duration <hours>），直接 get 会报：

Missing required option: --duration

查看 ATR 实际配置值用 tsm configuration get -k server.atr.enabled 等相关键，或查阅官方 ATR 文档。

7.4 identityStore 未设置就 initialize 被拒绝

Invalid Initialization Request: The identity store must be set before initialization.

按 5.1 通过 tsm settings import 导入 identityStore 定义并 apply 后再初始化。

7.5 settings import 后 pending-changes 为空

检查 JSON 的 configEntities 结构与 _type 字段拼写是否正确，identityStoreType 写错时 import 可能静默忽略实体。导入正确的文件会在 tsm pending-changes list 中出现 wgserver.authenticate 等键的变更。

八、参考链接

1. TSM 配置参考：https://help.tableau.com/current/server-linux/en-us/cli_configuration-set.htm
2. 动态配置键清单：https://help.tableau.com/current/server-linux/en-us/config_dynamic.htm
3. pending-changes 命令参考：https://help.tableau.com/current/server-linux/en-us/cli_pending-changes.htm
4. 身份存储配置：https://help.tableau.com/current/server-linux/en-us/authentication.htm