私有化部署研发管理平台怎么部署？完整步骤与常见报错处理

私有化部署研发管理平台，指的是把程序、数据库和附件都装进企业自己的服务器或内网环境，数据不再经过第三方。它解决的通常是三类约束：数据不能出内网、要和现有账号或审批体系打通，以及行业监管对存放位置有要求。

装起来其实不难，难的是把环境基线、上线配置和出错后的回退想清楚。下面按「先定前提、再走步骤、最后处理报错」的顺序，把私有化部署研发管理平台的部署过程讲一遍。每一步都给一个可以观察的结果，做到哪一步心里有数。

部署前先定三件事：形态、容量与安全基线

先定形态和资源，再动手装。顺序反过来，往往会重复搭一遍环境。

部署方式怎么选：一键安装包、容器与源码

以禅道项目管理软件为例，官方提供 Linux 一键安装包、Docker 镜像和源码包三种方式。选择依据是团队运维能力和后续升级方式，而不是哪个看起来更省事。

一键安装包已经包含 Apache、PHP 和 MySQL，装上即可运行，适合单机试跑和快速验证。Docker 方式把这套运行环境打包进镜像，适合已经在用容器编排的团队。源码方式最灵活，代价是要自己承担环境一致性。

容量基线：先估三个数字，再定服务器配置

服务器配置不用一开始就堆高，但要把三个数字先写下来：注册用户数、峰值同时在线人数、每月新增附件量。注册用户数影响账号和授权，同时在线人数决定资源，附件量决定存储增长。

常见的估法是按注册用户数的 10% 到 20% 估并发，再按业务高峰调整。官方 Docker 文档给出的测试环境起点是 1 核 CPU、1 GB 内存、10 GB 磁盘，推荐值为 2 核 CPU、4 GB 内存、50 GB 以上磁盘——这几个数字是测试基线，不是生产环境的推荐值。生产配置要按上面三个数字放大。更细的硬件、系统与数据库取值，可以参考服务器配置的完整说明。

两个容易忽略的细节：从 18.5 版本起，Linux 安装包分为 x86_64 与 arm64 两套，架构选错解压后无法启动；程序、数据库、备份和附件目录尽量落在不同分区，避免数据库写满把整台机器拖垮。

如果走信创路线，还要按操作系统、CPU 架构、数据库三层核对兼容性。禅道与统信 UOS、银河麒麟、达梦、鲲鹏等平台有可查的兼容性互认记录，具体组合仍以最新适配清单和当期认证证书为准。信创适配的核验清单建议在选型阶段就对着看一遍。

网络、端口与安全策略

这一段最容易被跳过，但它决定了后面会出现多少次「打不开」。

• 只对使用者开放 Web 端口，数据库端口不要暴露到公网。
• 云服务器要在安全组放行 Web 端口；内网服务器要确认本机防火墙和 SELinux 策略。
• 提前确定访问入口：直接用 IP 加端口，还是域名加 HTTPS。后者需要域名解析、证书和反向代理，属于上线前必须完成的工作。
• 约定变更窗口和责任人。部署过程通常需要停服或重启，写清谁执行、谁验证、出问题找谁。

部署步骤：从准备环境到服务可访问

官方文档把安装步骤按方式拆得比较散，下面按真实依赖顺序串起来，并把每一步的完成信号标出来。

第一步：准备安装包与运行环境

公网可达时，到禅道官网下载页面按操作系统和 CPU 架构选择对应版本与安装包。不要只挑版本号最大的那个：跨大版本升级对运行环境有额外要求，比如 20.0 及之后的版本不再支持 PHP 5.x，沿用旧版一键安装包直接升级会失败。

内网离线环境的准备要在有网的地方完成：

1. 下载安装包本体，以及官方文档列出的运行环境组件。
2. 采用容器方式时，在有网机器上拉取镜像并导出为文件，再拷进内网导入。
3. 校验文件完整性，比对外部提供的大小或校验值。传输中断造成的包损坏，报错信息通常看不出真实原因。
4. 确认目标服务器 /opt 分区的剩余空间，并为备份预留额外空间。

第二步：安装并启动服务

直接解压到 /opt 是官方推荐做法。不要先解压到别的目录再拷贝过去，否则文件所有者和读写权限会改变；也不要把整个目录设成 777 权限。

cd /optwget https://www.zentao.net/dl/zentao/<版本>/ZenTaoPMS.<版本>.zbox_64.tar.gztar xvzf ZenTaoPMS.<版本>.zbox_64.tar.gz/opt/zbox/zbox start/opt/zbox/zbox status

如果默认端口被占用，可以在启动时改端口：

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

Docker 方式则先建好数据目录，把程序目录和数据库目录分别挂载到宿主机，再启动容器：

sudo docker network create --subnet=172.172.172.0/24 zentaonetsudo docker run --name zentao -p 80:80 \  --network=zentaonet --ip 172.172.172.172 \  -v /data/zentao:/data \  -e MYSQL_INTERNAL=true \  -d hub.zentao.net/app/zentao:<镜像标签>

启动是否成功的判断信号很明确：命令回显启动成功，status 显示服务在运行，浏览器访问「服务器 IP 加端口」能看到登录页。容器方式则看容器状态是否为运行中、日志里有没有报错。

第三步：完成初始化与管理端配置

安装只是让程序跑起来，这一步才让它变成团队的系统。

• 第一件事是改掉默认账号和密码。禅道默认管理员账号是 admin、初始密码是 123456，这属于公开信息，上线前必须改。
• 确认数据库连接参数、数据目录和附件目录，并记入运维文档。
• 设置组织名称、语言和时区。时区设错会直接反映在时间记录和统计报表上，后期修改涉及历史数据，尽量一次设对。
• 指定备份目录并确认可写。备份目录不与其他高写入目录同盘更稳妥。
• 正式环境不要导入演示数据，或导入后清理干净。

第四步：上线前必须落实的配置

下面这几项没做完就把系统开放给团队，出问题的概率会明显升高。

域名与 HTTPS 有两种常见做法：直接改集成包里的 Apache 配置加载证书，或在前端加一层 Nginx 反向代理。用反向代理时注意保留原有访问路径规则，否则容易出现登录后跳转异常。

第五步：验证部署是否真的成功

部署完成的判断标准不是「页面能打开」，而是下面这些可观察的结果：

• 服务自启：重启服务器后服务能自动启动。
• 访问入口：域名加 HTTPS 可以访问，办公网内外表现一致。
• 数据完整：迁移前后的项目、需求、任务、Bug 与附件数量对得上。
• 权限正确：抽查管理员、项目负责人、普通成员三类角色，可见范围与操作权限符合设计。
• 通知可达：指派任务、提交 Bug 等动作能触发通知。
• 备份可恢复：至少完成过一次真实的恢复演练。
• 应急信息归档：管理员账号、数据库账号与端口、备份路径与周期，集中记录在一处。

如果是从旧系统迁移过来，还有一条硬性前提：迁移前后的版本必须保持一致。旧系统版本较低时，先把旧服务器升级到目标版本，再在新服务器安装同版本，最后执行迁移。数据迁移的完整顺序与注意事项，可以按数据迁移的步骤对照执行。

常见报错处理：先看现象，再定位原因

报错信息通常只说明「哪里失败了」，不直接说明「为什么失败」。先按现象分类，再逐个排除，比反复重装快得多。

页面打不开或提示无法访问

按顺序查三处：

1. 端口是否被占用或没有监听。
2. 本机防火墙、SELinux 是否拦截。
3. 云服务器安全组是否放行 Web 端口。

官方文档也提示，网页无法访问时先关闭防火墙和 SELinux 再刷新验证。验证通过后，要按最小开放原则把策略收紧回来，不要为了省事长期关闭。

服务启动失败

如果执行 /opt/zbox/zbox start 立刻报错，常见原因是安装包与系统内核版本不匹配。用 uname -a 查看内核信息，优先在 4.x 以上内核的系统（例如 Ubuntu 17+、CentOS 7.x）上安装。

Windows 一键安装包还有两条特有规则：目录必须部署在某个硬盘分区的根目录，例如 C:\xampp；如果 MySQL 能启动但 Apache 报「系统无法执行指定的程序」，需要先安装 vcredist_x86.exe。

数据库相关报错

现象是服务卡在数据库连接、页面提示数据库错误，或启动日志里出现 MySQL 异常。按顺序确认：

• 端口是否冲突，磁盘是否写满。
• 数据目录的属主与权限是否正确。
• 用的是内置数据库还是外置数据库，连接参数（地址、端口、账号、密码、库名）是否与实际一致。

无法当场定位时，从备份恢复，不要在同一份数据上反复重装。

安装向导提示缺少 PHP 扩展

源码方式安装时，安装向导的系统检查会列出缺失的扩展。禅道运行需要 pdo、pdo_mysql、json、filter、openssl、mbstring、zlib、curl、gd、iconv；企业版和旗舰版还需要 zip、xml、ldap、bcmath。

处理方式是在 php.ini 中加载对应扩展，然后重启 Apache。Linux 下优先用系统包管理器安装，例如在 Debian、Ubuntu 下安装 PHP 的 pdo 相关包。

附件打不开或丢失

最常见的原因是备份时没有勾选附件，或只备份了数据库。处理方式是从包含附件的备份中恢复，之后把附件目录纳入备份范围。

跨操作系统迁移（例如从 Windows 换到 Linux）还有一步容易漏：迁移完成后要在后台把备份目录设置改成对应操作系统的目录结构。

邮件或 IM 通知发不出去

先检查 SMTP 参数是否正确，再确认出站端口有没有被防火墙或安全策略拦截。用一次测试发送来定位问题，通常比直接翻日志更快。

升级后报错或白屏

跨大版本升级、运行环境版本不匹配，都可能导致升级后白屏。处理原则是先停止继续操作，按官方升级说明排查；无法定位时，回退到升级前的数据库与附件备份。

出错后的回退：把风险收在备份里

回退能不能用，取决于事前有没有准备。三条原则可以先记住：

• 数据库和附件放在同一份备份里。
• 升级或迁移前必须做一次完整备份。
• 恢复步骤要提前演练过。

出问题时先恢复服务，再分析原因，不要在故障状态下边查边改。备份文件要定期同步到另一台机器或对象存储；只留在同一台服务器上，服务器故障时备份会一起丢。

部署完成之后，工作会转到另一条线上：备份是否按期执行、版本升级如何评估、使用人数增长后是否需要扩容。这些日常节奏，才是私有化部署研发管理平台长期可靠的来源。把环境基线、上线配置和回退路径这三处想清楚，一次装好的概率就高得多。