Kiwi TCMS 16.2 升级指南：安全更新、数据库迁移与 API 兼容性检查

预计阅读时间：9 分钟

Kiwi TCMS 面向手动测试与自动化测试提供统一的测试管理能力，包括缺陷跟踪器集成、搜索、访问控制、自动化框架插件、可视化报告和 API。此次发布信息指向 16.2，但摘要中的版本说明出现了 16.1，且变更列表被截断。因此，本文不推断具体漏洞编号或接口字段，而是围绕摘要明确提到的安全更新、数据库迁移、API 变化和错误修复，整理一套可以落地的升级方法。

小版本升级也可能改变运行边界

“16.x 的小版本更新”不等于可以直接替换镜像。摘要明确提到了数据库迁移和 API 更改，这两类变化都可能影响现有环境。

数据库迁移会改变表结构、索引或数据内容。升级过程一旦中断，简单回退应用镜像未必能让旧版本继续读取已经迁移的数据库。API 更改则可能影响 CI 任务、自动化测试结果上传脚本，以及 Jira、Bugzilla 等外部缺陷系统的集成程序。

安全更新也值得单独处理。Kiwi TCMS 保存测试计划、执行记录、产品信息和用户权限，通常还持有外部系统的访问凭据。升级后应复核管理员范围、服务账号权限和集成密钥，而不能只确认页面能够打开。

升级前建立可恢复点

可以这样实践：先记录当前容器、镜像和数据库状态，再制作数据库备份。下面以 Docker Compose 和 PostgreSQL 为示例；请把服务名、数据库用户和数据库名替换为实际配置。如果环境使用 MariaDB/MySQL，需要改用对应的备份工具。

set -euo pipefail

mkdir -p backups
STAMP="$(date +%Y%m%d-%H%M%S)"

# 按实际 Compose 服务名调整 kiwi_web 和 kiwi_db。
docker compose ps > "backups/compose-${STAMP}.txt"
docker compose images > "backups/images-${STAMP}.txt"

docker compose exec -T kiwi_db \
  pg_dump -U kiwi -d kiwi --format=custom \
  > "backups/kiwi-${STAMP}.dump"

# 确认备份文件不是空文件。
test -s "backups/kiwi-${STAMP}.dump"
ls -lh "backups/kiwi-${STAMP}.dump"

备份完成后还要验证恢复流程。最可靠的验证方式是在隔离数据库中执行 pg_restore，然后用旧版本或待升级版本连接该副本进行检查。仅看到备份命令退出码为零，不足以证明备份可恢复。

升级前建议同时保存以下信息：

当前 Kiwi TCMS 镜像标签和镜像摘要；
Compose、Kubernetes 或反向代理配置；
数据库版本及扩展列表；
外部 Bug 跟踪器配置和服务账号权限；
调用 Kiwi TCMS API 的脚本、流水线和插件清单。

把升级拆成迁移与验证两个阶段

如果使用容器部署，可以这样改造升级流程。示例中的镜像标签只是待替换变量，应以项目发布的实际镜像名称和标签为准。

set -euo pipefail

export KIWI_TCMS_IMAGE="your-registry/kiwi-tcms:16.2"

# 拉取目标版本，但暂不删除旧镜像。
docker pull "${KIWI_TCMS_IMAGE}"

# 在 compose.yaml 中更新镜像后启动服务。
docker compose pull
docker compose up -d

# 检查启动状态和迁移日志。
docker compose ps
docker compose logs --since=10m kiwi_web

数据库迁移的具体命令应以该版本的官方部署说明和镜像入口行为为准。有些镜像会在启动时自动迁移，有些部署则要求显式执行迁移命令。不要在未确认机制时并行启动多个执行迁移的应用实例，否则可能产生锁竞争或重复迁移。

完成启动后，不要只检查首页。至少执行一轮冒烟测试：

管理员和普通测试人员分别登录；
搜索既有测试计划、测试用例和执行记录；
创建一条临时测试执行并更新结果；
验证缺陷跟踪器链接或同步操作；
打开可视化报告并核对关键统计值；
运行一次自动化结果上报流水线；
检查未授权用户是否仍被正确拒绝。

用契约测试捕获 API 变化

摘要提到 API 变化，但没有给出端点和字段细节。这里可以建立一个不依赖具体业务字段的 API 冒烟脚本，并根据实际 Kiwi TCMS API 文档补充路径、认证方式和断言。以下脚本假设部署提供 Bearer Token，并存在可用于健康检查的 API 地址；运行前必须替换 KIWI_BASE_URL、KIWI_API_PATH 和令牌。

#!/usr/bin/env bash
set -euo pipefail

: "${KIWI_BASE_URL:?set KIWI_BASE_URL, for example https://tcms.example.com}"
: "${KIWI_API_TOKEN:?set KIWI_API_TOKEN}"
KIWI_API_PATH="${KIWI_API_PATH:-/api/}"

response="$(mktemp)"
trap 'rm -f "$response"' EXIT

status="$(curl --silent --show-error \
  --output "$response" \
  --write-out '%{http_code}' \
  --header "Authorization: Bearer ${KIWI_API_TOKEN}" \
  --header 'Accept: application/json' \
  "${KIWI_BASE_URL%/}${KIWI_API_PATH}")"

if [[ "$status" != "200" ]]; then
  echo "API smoke test failed with HTTP ${status}" >&2
  cat "$response" >&2
  exit 1
fi

python3 -m json.tool "$response" >/dev/null
echo "API smoke test passed"

这段脚本只能验证认证、HTTP 状态和 JSON 格式。真正的兼容性检查还应固定一份脱敏响应样本，比较关键字段的名称、类型、分页结构和空值行为。对于会写入数据的接口，应在临时项目中执行创建、查询、更新和删除闭环，避免污染生产测试记录。

上线决策：安全收益与兼容性成本一起评估

这次发布涉及安全更新，通常不适合长期搁置；但数据库迁移与 API 变化又要求团队准备回退方案。更稳妥的顺序是：先在生产数据副本上演练迁移，再运行 UI、权限、集成和 API 测试，最后安排生产升级窗口。

上线前可以用这份清单收口：

已确认目标版本确实为 16.2，并核对完整发布说明；
已验证数据库备份能够恢复，而不只是能够生成；
已盘点所有 API 客户端、自动化插件和 Bug 跟踪器集成；
已测试管理员、测试人员和只读用户的权限边界；
已记录旧镜像、配置和数据库回退步骤；
已在升级后检查迁移日志、错误率和后台任务；
已轮换或复核高权限服务账号与集成凭据。

Kiwi TCMS 的价值来自测试流程、外部缺陷系统和自动化流水线之间的连接。升级是否成功，不能只看服务进程是否存活，而要看这些连接是否继续以正确的权限和数据契约工作。