测试管理软件操作指南：私有化部署与初始化配置的完整步骤

测试用例散在 Excel，Bug 记录在聊天工具，版本测试结果靠人工汇总，准备迁到内网系统时，团队通常会在权限和流程初始化上遇到阻力。把测试管理软件部署到企业自己的服务器上，解压安装包通常只要几分钟，更影响后续使用的是账号、权限和测试流程是否在首次配置时设置正确。本文以禅道 Linux 一键安装包为主线，Docker 为分支，Windows 与源码部署只做选择说明，按准备、部署、初始化、验收和常见问题展开。

一、先判断：私有化部署适合什么场景

当测试数据、Bug 记录和附件需要留在内网，或者企业有等保、审计、信创要求时，私有化部署更合适。它把数据控制权交给企业，也把服务器维护、备份、升级和安全加固的责任交给企业。团队没有基本的 Linux 运维能力和固定的备份责任人时，建议先补齐这两项。

该系统本地部署提供多种入口，选择哪一种，取决于现有环境和运维习惯。

截至 2026 年 10 月，具体版本、镜像标签和系统兼容范围以官网下载页为准。不同版本的模块范围、授权方式和升级支持，以官网说明及合同为准。一键安装包和 Docker 内置的数据库更适合快速验证，不建议直接承载生产数据。

二、部署前准备：先把不可逆风险前移

先确认 CPU 架构。官方文档说明，从 18.5 版本开始，Linux 一键安装包分为 x86_64 和 arm64 两个包，下载错包会直接导致服务无法启动。执行 uname -m，确认是 x86_64 还是 aarch64。

再确认端口占用。一键安装包默认用 80 端口提供 Web 访问、3306 端口连接 MySQL。执行 ss -lntp | grep -E ':(80|3306)[[:space:]]'，如果端口已被已有 Web 服务或其他 MySQL 实例占用，提前规划 8080、3307 这类替代端口。

同时确认目录和磁盘。安装包需要直接解压到 /opt，不要先解压到其他目录再拷贝，否则文件所有者和读写权限可能改变。官方文档也提醒，不要图省事把整个目录设为 777。执行 df -h /opt 确认空间，再按实际运行用户设置目录归属。

还要确认网络路径。内网访问要放行服务器防火墙，云服务器还要放行安全组；如果启用了 SELinux，先确认它是否会拦截 Web 端口。具体放行方式按企业网络规范执行，不建议为了排障长期关闭安全策略。

接着确认备份位置。部署前就确定数据库、附件和配置文件的备份目录，建议放在另一块磁盘或另一台服务器上。部署动作可以重来，已经产生的测试数据不能靠重装恢复。

服务器规格没有一套适用于所有团队的固定答案，建议按并发用户数、附件量和备份窗口评估，先用试点环境压测，再确定生产规格。

三、用 Linux 一键安装包完成部署

Linux 一键安装包把 Apache、PHP、MySQL 和 XXD 打包在一起，适合希望减少环境拼装的团队。下面的版本号请替换为官网当前版本。

1. 下载并解压到 /opt

cd /opt
wget https://www.zentao.net/dl/zentao/{版本号}/ZenTaoPMS.{版本号}.zbox_64.tar.gz
tar xvzf ZenTaoPMS.{版本号}.zbox_64.tar.gz

执行后，/opt/zbox 目录应当存在。成功信号不是命令没有报错，而是目录结构完整、属主没有被意外改成其他用户。 如果下载 arm64 包，文件名和架构参数以官网下载页为准。代码块中的版本号是占位符，请从下载页复制实际链接，不要原样执行。

2. 启动服务并检查状态

/opt/zbox/zbox start
/opt/zbox/zbox status

停止和重启分别使用 /opt/zbox/zbox stop、/opt/zbox/zbox restart。18.10 版本起还提供 /opt/zbox/zbox check，用于按配置检查服务状态。

启动成功的标志是状态表里 Apache、PHP、MySQL、XXD 均显示 running。如果只有部分服务起来，不要急着访问页面，先看 MySQL 是否因端口冲突或目录权限退出。 需要开机自启时，按服务器发行版的方式把启动命令加入自启配置，不要依赖当前终端会话。

3. 访问系统并调整端口

服务启动后，浏览器访问 http://服务器IP:Apache端口。默认管理员账号是 admin，默认密码是 123456，首次登录后需要立即修改。页面打不开时，按服务状态、端口监听、本机防火墙、SELinux、云安全组的顺序排查，这样能更快区分是应用没起来，还是网络没放行。

需要改端口时，可以在启动命令中指定：

/opt/zbox/zbox --aport 8080 --mport 3307 start

这条命令把 Apache 端口改为 8080、MySQL 端口改为 3307。改完端口后，访问地址、防火墙规则和备份脚本都要同步更新，否则会出现本机可访问但同事无法访问的情况。

4. 选择 Docker 部署时的差异

已有容器平台时，可以从 hub.zentao.net/app/zentao 拉取镜像。Docker 容器把需要持久化的数据集中放在 /data，运行时需要把这个目录挂载到宿主机，否则容器重建后数据会丢失。

docker run -d \
  -v /data/zentao/data:/data \
  -p 80:80 \
  -e MYSQL_INTERNAL=true \
  hub.zentao.net/app/zentao:latest

MYSQL_INTERNAL=true 会启动容器内置 MySQL，默认账号为 root、密码为 123456。官方文档明确说明，内置数据库仅供测试使用，生产环境建议使用外部数据库。使用外部数据库时，通过 ZT_MYSQL_HOST、ZT_MYSQL_PORT、ZT_MYSQL_USER、ZT_MYSQL_PASSWORD、ZT_MYSQL_DB 传入连接信息。需要长期维护时，优先使用 Compose 管理应用、数据库和缓存，具体示例可参考Docker 与 Kubernetes 部署文档。

四、初始化配置：账号、组织、权限与测试流程

看到登录页只说明部署完成了一半。初始化配置决定这套测试管理软件以后是否好管：谁能进、能看什么、测试任务怎么流转、Bug 由谁关闭，都要在这一步定下来。

1. 首次登录先处理账号安全

用 admin 和默认密码登录后，系统会提示修改弱口令。先完成密码修改，再添加业务数据。 密码应包含大小写字母、数字和符号，并与企业统一身份规范保持一致。较新版本可以在后台的安全页面维护密码策略，具体菜单名称以当前版本界面为准。

随后补齐公司名称、时区等基础信息，避免任务时间、日志时间和备份时间出现偏差。超级管理员账号不要多人共用；日常管理可以另建管理员账号，保留一个应急账号并单独保管。邮件通知、LDAP 等集成可以等主流程验证通过后再接，不要在首次上线时同时启用多项集成。

2. 按角色配置部门、用户和权限

该系统主要通过权限分组分配权限。建议按组织下的部门、用户、权限顺序配置：先搭部门结构，再添加用户，最后建立权限分组并维护成员。

权限配置通常分三步：在权限分组列表新增分组，在权限维护中勾选该角色可访问的模块和操作，在成员维护中把用户加入分组。用户加入分组后获得对应权限；多分组场景以当前版本权限页面为准。分组权限决定可执行的操作，视野设置进一步限制可见的产品和项目范围，两者要一起检查。

配置完成后，用一个普通测试账号登录验证，不要只用管理员账号自测。管理员能看到全部内容，普通账号只能看到授权范围，权限边界才算配置到位。

3. 建立测试管理的最小流程

测试管理软件的价值在流程，不在单个菜单。初始化时先建立一个可运行的最小流程：建产品、划分模块、建用例、提测试单、执行并提交 Bug、回归关闭。

建产品与模块。 产品是需求和用例的归属容器，模块决定后续筛选效率。建议先按系统或业务域划分一级模块，再按功能点建二级模块，不要一开始就铺到过细的层级。

建用例库。 进入测试相关模块，在用例库中整理公共用例，或在产品用例中直接创建当前版本用例。填写标题、前置条件、步骤、预期结果、优先级和所属模块。公共用例库中的用例通常需要先导入当前产品用例，提交测试单时才能关联。历史用例可以通过导入方式迁移，但导入后要抽查步骤和预期结果是否错位。首批用例不必追求数量，先把冒烟测试和核心回归路径覆盖完整。

提交测试单。 在项目或测试模块中提交测试单，选择所属产品、测试版本、负责人和起止时间，再关联本轮要执行的用例。把用例指派给具体执行人后，按页面提示开始测试单，再进入执行环节。

执行并提交 Bug。 按通过、失败、阻塞等状态记录用例结果；失败项提交 Bug 时，尽量关联对应用例和需求，后续回归才能追到源头。Bug 修复后由测试人员回归并关闭，开发人员负责更新解决状态，这个边界要在权限分组里体现。

输出测试结果。 测试完成后关闭测试单，并通过测试报告或统计视图查看用例执行率、Bug 分布和遗留风险。如果团队只看测试是否完成，不看用例覆盖和 Bug 闭环，测试管理软件容易只剩下记录功能。

五、上线验收与备份恢复

部署完成后，先补齐生产环境的安全配置，再按清单验收。页面能打开只是最低条件，不能说明系统可以交付使用。

1. 生产环境先补三项安全配置

Web 访问建议通过反向代理启用 HTTPS，避免账号密码长期以明文传输。3306 端口不要对公网开放，只允许应用服务器或内网地址访问。数据库管理入口限制在本机或内网，设置独立验证账号，不使用默认口令。

2. 按清单验收

3. 备份与恢复

较新版本可以在后台的系统设置下分别进入备份和定时页面，执行数据备份、配置自动备份，具体菜单以当前版本为准。使用 Linux 一键安装包时，也可以先停止服务，再备份整个 /opt/zbox 目录；使用 Docker 时，重点备份挂载到宿主机的 /data 目录。具体路径以备份文档为准。

恢复按备份方式走两条路径。整目录备份：停止服务，替换 /opt/zbox，启动后验证；数据级恢复：在隔离环境恢复数据库、附件目录和必要的配置文件，再启动验证。恢复前确认目标环境版本一致、目标库不是生产库，恢复失败时保留原备份，不要覆盖唯一副本。 建议每季度做一次恢复演练；备份没有经过恢复验证，可靠性就无从确认。

六、常见问题与排障顺序

排障时不要东改一处、西改一处。建议固定顺序：先看服务状态，再看端口监听，再看本机防火墙和 SELinux，再看云安全组和反向代理。这个顺序能把应用故障和网络故障分开。

页面打不开，Linux 一键包先执行 /opt/zbox/zbox status；Docker 部署先执行 docker ps -a 查看容器状态，再用 docker logs <容器名> 查看应用和数据库日志。服务未运行就看 MySQL 日志和端口占用；服务运行但本机访问不了，检查防火墙和安全组；本机能访问、其他机器不能访问，多半是监听地址或网络策略问题。

MySQL 启动失败，常见原因是 3306 端口被占用、数据目录权限不正确，或者首次启动时未处理弱口令提示。Docker 部署还要检查宿主机挂载目录权限。不要直接删除数据目录重来，先确认是否已有业务数据，再按备份恢复流程处理。

附件上传失败，先看磁盘空间，再看 PHP 的上传大小、POST 大小和执行时间限制。Docker 部署可以通过 PHP_UPLOAD_MAX_FILESIZE、PHP_POST_MAX_SIZE、PHP_MAX_EXECUTION_TIME 调整，改完后重启容器验证。

普通用户看不到某个模块，先检查权限分组是否勾选了对应模块，再检查视野设置是否限制了产品范围，最后让用户重新登录。权限修改后不重新登录，容易被误判为配置未生效。

准备升级前，先完整备份，再阅读与当前环境对应的升级文档，选择无人访问的时间窗口执行。升级后复查权限，因为新版本可能增加或调整功能项。

七、上线后的最小运维清单

测试管理软件的私有化部署不是一次性项目。上线后建议固定四件事：每天查看服务状态和磁盘空间，每周确认自动备份是否成功，每月复查权限分组和离职账号，每季度做一次恢复演练和版本安全更新。

如果团队刚开始使用，建议先选一个项目试点，完成一轮需求、用例、测试单、Bug、回归的完整流程，再逐步接入更多产品和团队。部署解决的是系统部署在哪里，初始化解决的是团队怎么用，后者更影响这套测试管理软件能否长期留在研发流程里。

八、FAQ：上线前后常见问题

1. 内网服务器不能访问外网，安装包和镜像怎么准备？

在可联网机器下载对应架构的安装包，校验文件完整性后传入内网。Docker 环境可以用 docker save 导出镜像，再在内网用 docker load 导入；不要为了临时下载而长期开放外网端口，也不要用来源不明的镜像。

2. 已经在用 Jira 或 Excel，先迁哪些数据？

先迁产品、模块和当前版本用例，再迁未关闭的 Bug。已关闭的历史 Bug 可以按合规要求归档，不必全部导入；迁移前统一字段、状态和负责人，能减少导入后的返工。

3. 测试团队只有几个人，权限分组要不要做细？

人数少时不必照搬大团队的分组体系，但测试负责人、测试工程师、开发三类权限建议分开，尤其要控制 Bug 关闭权限。人员增加后，再按项目或产品继续细化。

4. 私有化部署后，版本升级频率怎么定？

安全补丁优先安排，功能版本可以按季度或半年评估。升级前在测试环境验证插件、权限和附件，确认无异常后再安排生产窗口，不建议长期停留在旧版本。

5. 服务器更换或机房迁移，怎样保证测试记录不丢？

先在新服务器部署同版本，完成一次恢复演练后再切换访问地址。切换后保留旧服务器一段时间，确认登录、用例、附件和权限都正常，再安排下线。