在不少小团队里缺陷的流转路径是这样的测试在群里发一段话加两张截图开发回一句收到三天后有人问那个问题修了吗然后所有人开始往上翻聊天记录。等到版本要发的时候才发现有一半问题说不清是漏了还是修了。我前后帮几个小团队搭过自建缺陷管理系统最后落到同一套组合上在一台闲置的 Windows 机器上装禅道ZenTao再用 Cpolar 把一个公网地址映射到这台机器的本地端口让在家办公或出差在外的同事也能提交和查看问题。整套东西不需要公网 IP不需要动路由器从零到能用大约两小时。这篇就按我实际操作的顺序把安装、映射、踩坑和运维一件件讲清楚适合手上有台吃灰主机、又不想为几个人的缺陷管理去付费订阅的读者。1. 先在纸上把账算清楚为什么缺陷要落在自己的一台机器上1.1 聊天记录当需求池代价藏在三个月后很多人以为缺陷管理的痛点是记录麻烦其实真正的痛点是不可检索、不可统计、不可追责这三件事。聊天工具里一条消息发出去它的生命周期就绑在有没有人记得上而不是绑在问题有没有关闭上。三个月后你要复盘这个版本为什么延期聊天记录给不了你答案因为它没有状态字段没有责任人字段没有版本归属字段。我自己踩过的一次具体教训是某个客户侧反馈的显示错位问题在群里被提了三次每次都被先放着糊过去最后上线当天才被发现。事后我去追溯发现三次反馈分别落在三个不同的群互相之间没人知道对方存在。这类事情发生过一次你就会明白一个能打标签、能挂状态、能按版本筛选的系统值多少钱。更隐蔽的成本是决策成本。没有系统的时候每次发版前都要开会问还有没有没修的回答质量完全取决于在场人的记忆。有了系统发版前只需要拉一个未关闭且属于本版本的列表五秒钟出结果。这个差别在团队人数超过五个之后会急剧放大。1.2 一台闲置 Windows 主机的现实价值为什么选 Windows 而不是折腾一台 Linux说句实在话除非你手上正好有一台常开的 Linux 服务器否则在小团队场景里Windows 的优势非常直接随便找一台办公用的旧台式机就能上装完不用管出问题身边所有人都能上手看一眼。而一台装了 Linux 的机器一旦负责的人休假整个系统就无人敢碰。禅道官方提供了 Windows 一键安装包把 Web 服务、数据库、运行环境全部打在一起装完即用不需要你先去配一套运行环境。这一点对非专业运维的人来说价值极大——它把部署一套系统降级成了装一个软件。当然代价也要说清楚一键包体积不小内置的组件版本相对保守性能上限有限适合五十人以内、日活不高的场景。如果你预期要支撑几百人并发这套方案不合适那时候应该考虑独立部署或者别的产品。但对绝大多数五到二十人的小团队一台四核八线程、8G 内存、256G 固态的旧机器完全够用甚至有点富余。1.3 动手指之前必须定下来的四件事我在动手前一定会先确认下面四件事因为每一项定错了后面都要返工需要确认的事为什么重要我的常见取值本地监听端口与机器上已有的服务抢端口是最常见的失败原因80 被占用就退到 8080 或 8090数据目录位置决定后面备份怎么拷、拷什么单独放在非系统盘目录下机器是否会关机关机等于服务下线映射地址会失效明确约定这台机器不关谁来管账号管理员账号丢失等于系统丢失两个管理员账号密码分开保管端口这件事值得多说一句。Windows 机器上十有八九已经跑着别的东西安装包默认想占 80 端口一旦被占装完程序能启动但页面打不开新手很容易卡在这里。安装向导里如果允许自定义端口一开始就避开 80直接填 8080 这种冷门值能省掉后面半小时的排查。数据目录同理。一键包默认把数据放在安装目录下的子目录里如果安装时一路下一步装进了 C 盘 Program Files后面重装系统或者做磁盘清理时会非常麻烦。安装路径建议直接指到一个独立分区比如D:\zentao所有数据都在这个目录里备份就是整个目录拷走简单可靠。提示机器负责人和系统管理员最好是同一个人或者至少有一个明确的交接约定。我见过太多次装的人离职了没人知道管理员密码的情况。2. 禅道一键包在 Windows 上的落地过程与每一步的真实意图2.1 版本与安装包形态的选择逻辑进到下载页会看到一堆选项容易挑花眼。判断标准其实只有两条选 Windows 一键安装包选带LTS或者长期维护标记的版本。一键安装包的文件名通常长这样ZenTaoPMS.x.x.x.win64.exe中间的数字是版本号。它的本质是把 Web 服务器、数据库、运行环境打包成一个自解压安装程序装完在安装目录里能看到几个子目录分别对应运行环境、数据库数据、程序代码、日志。为什么不用源码包或者容器镜像源码包需要你自己准备运行环境、配置数据库连接、调虚拟主机对没有运维经验的人来说是几倍的工作量。容器镜像虽然干净但 Windows 上跑容器本身就要先装一套运行时反而多一层依赖。小团队的部署原则是能不自己拼就不自己拼出问题时排查面越小越好。版本选择上新版本功能多但可能有小毛病长期维护版相对保守。缺陷管理系统这种基础设施类的东西我的倾向是选长期维护版功能少一点无所谓别在关键时候打不开。2.2 安装向导里那些下一步背后发生了什么安装过程本身很简单但每一步在做什么值得说清楚因为出问题时你需要知道该去哪儿看。选择安装路径。这一步决定了后面所有文件的归属。填D:\zentao安装程序会在这里铺开运行环境、程序文件和数据目录。选择端口。向导里如果出现端口设置项填一个没被占用的值比如 8080。这一步决定后面浏览器地址栏里写什么。设置管理员密码。有些版本会在这里让你设数据库或管理员口令设完记下来。等待解压和初始化。这一步耗时最长机械硬盘上可能要几分钟期间不要点取消。完成并启动。装完通常会有一个启动入口双击之后会弹出一个类似控制台的窗口里面能看到服务的启停状态。安装完成后你会看到安装目录结构大致是D:\zentao ├── xampp\ # 运行环境Web 服务 数据库 ├── zentao\ # 程序代码 ├── start.bat # 启动入口 └── ...这个结构告诉你一件事程序代码和数据是分开存放的数据在运行环境的数据库目录下。后面做备份要么整目录拷要么用系统内置的备份功能导出。2.3 首次启动与访问验证的三层检查装完不要急着打开浏览器先按三层顺序验证出问题能快速定位在哪一层第一层进程层。双击启动入口观察控制台窗口里有没有报错。正常情况会看到 Web 服务和数据库先后启动的提示。如果窗口一闪就消失通常是端口被占用或者权限不足。第二层端口层。打开命令行执行netstat -ano | findstr :8080看到LISTENING状态说明端口已经在监听。如果什么都没输出回到第一层继续查。第三层应用层。浏览器访问http://127.0.0.1:8080端口换成你实际设的应该能看到登录页。这里有个细节用127.0.0.1而不是localhost因为localhost有时会先解析到 IPv6 的::1而服务只监听了 IPv4结果就是明明启动了却打不开这类问题非常能浪费人的时间。首次登录的默认账号通常是admin密码123456登录后会强制要求改密码。第一件事就是改掉它不要留到后面。改完顺手在后台把公司名、显示语言、时区这些基础信息填好这些东西后面会出现在导出的报表上。2.4 让数据有地方住目录规划与备份开关系统能打开只是开始真正决定这套东西能不能长期用下去的是数据管理。我一般做三件事第一把数据目录从系统盘挪走。如果已经装在 C 盘又不想重装可以在安装目录里找到数据库数据目录停服务后整体移动到D:\zentao-data再用目录符号链接指回去。这一步操作有风险做之前先整目录复制一份留底。第二打开系统内置的备份。禅道后台有备份功能可以设置自动备份周期和保留份数。我一般设成每周一次、保留四份够覆盖一个月的回溯需求。备份文件默认会放在安装目录下的备份文件夹里记得确认这个目录所在磁盘有足够空间。第三加一个外部拷贝。内置备份再方便它和原始数据在同一块盘上盘坏了就一起没了。我习惯再加一个简单的外部拷贝用系统的计划任务每周把备份目录复制到一个移动硬盘或者另一台机器的共享目录里。命令很简单robocopy D:\zentao\backup E:\zentao-backup /MIR /R:1 /W:1这一行就能把备份同步出去/MIR表示镜像同步删掉的文件在目标端也会删掉。加上它之后心里踏实很多。3. 把内网地址映射到公网Cpolar 该插在架构的哪个位置3.1 直接放行防火墙端口这条路为什么走不通装完之后同一个局域网里的同事用http://你的内网IP:8080就能访问了。但问题在于在家办公的人不在这个局域网里访问不到这个内网地址。最直觉的想法是把 Windows 防火墙的这个端口对外开放再把路由器的端口映射指过来。这条路在技术上可行但我不建议走原因有三条大多数家用宽带没有固定公网地址运营商会做地址转换你做不了入向映射即使有把一台办公机器的端口直接暴露在公网也很危险缺陷系统里会有客户信息、内部计划、代码片段被扫到就是一个洞维护成本高地址一变所有同事的收藏夹全失效。所以我选的方向是不动网络设备由一台在内网的机器主动向外建立一个映射关系外部通过这个映射地址访问回来。这就是 Cpolar 这类工具的位置——它不是在你的网络里开一个洞而是让内网机器主动连出去把外部请求带回来。3.2 客户端与隧道的实际安装配置过程整个流程分注册、安装、建映射三步我按实际操作顺序写。第一步注册并拿到授权凭据。在官网注册账号后登录后台能看到一个授权码一串字符后面客户端登录要用。第二步安装客户端。下载 Windows 版客户端一路下一步装完。装完之后它会有一个本地管理界面通常在http://127.0.0.1:9200这个地址上浏览器打开就能看到。第三步登录并创建映射。在管理界面里填入授权码完成登录然后新建一条映射规则关键参数只有两个参数填什么说明协议类型HTTP禅道是网页服务选 HTTP本地地址127.0.0.1指向本机本地端口8080必须和禅道实际监听的端口一致二级子域名自定义一段决定最终访问地址的前缀填完保存界面上会生成一个公网访问地址形如https://xxxx.r2.cpolar.top或者https://你设的前缀.cpolar.cn。把这个地址发给同事他们就能从外网打开了。这里有个非常常见的错误本地端口填了 80但实际服务在 8080。映射建立成功、地址也能打开但页面是空的或者 502。所以建完映射后一定要立刻用浏览器实际访问一次生成的公网地址别只看到创建成功就以为完事。3.3 免费额度、地址变化与固定子域名的取舍免费方案能满足小团队偶尔用但有两条限制必须提前知道否则会在某天早上被同事追问怎么打不开了。第一条是地址会变。免费方案分到的随机子域名不是永久的过期或者客户端重启后可能变化。变化之后所有人的收藏夹、别人发过的链接全部失效。解决办法是申请一个固定的二级子域名配置到映射规则里这样地址就固定下来了。第二条是带宽和并发有限。免费方案的带宽是共享的打开一个列表页还行上传大附件、批量导出报表就会明显慢。如果团队里有人习惯把几百兆的日志文件往缺陷单里塞体验会很差。我的取舍建议很直接如果这套系统要长期用、要发给客户或者外部协作方直接申请固定子域名。这一步花的时间和精力比后面每个人来找你一次链接怎么打不开了少得多。如果只是自己临时在外面看一眼免费方案完全够用。3.4 打开公网入口之后必须补的三道门公网地址一出来这套系统就从一个内网工具变成了对外服务有三件事必须补上否则等于把门开着。第一道改掉所有默认口令。管理员密码、数据库口令任何还停留在初始值的都要换掉。我见过有的实例装完三年没改过初始密码只是因为没人会去访问吧。第二道收紧账号发放。不要给所有人开管理员。禅道有比较清晰的角色划分开发、测试、产品各取所需即可。账号宁可少开需要时再加不要图省事一把梭。第三道把映射的访问范围想清楚。如果这套系统只在工作时间用可以考虑在非工作时间把映射停掉减少暴露时长。如果某些页面涉及敏感信息检查一下匿名访问是否被关掉。注意公网地址不是密码。任何人拿到地址就能看到登录页所以真正的安全边界在账号体系和权限配置上不在地址本身。4. 五类真实故障的排查链路从现象倒推到根因4.1 本机都打不开先看进程再看端口现象装完双击启动入口浏览器访问http://127.0.0.1:8080一直转圈或者直接报无法访问。排查链路是这样走的第一步看启动窗口有没有关掉。有些版本的控制台窗口一旦被关闭服务就停了。窗口在不在是第一个判断点。第二步跑netstat -ano | findstr :8080。没输出说明服务根本没在监听问题在启动阶段。这时候去看安装目录里的错误日志通常是端口被占用或者数据库没起来。第三步如果端口在监听但还是打不开换http://127.0.0.1:8080试排除localhost解析到 IPv6 的可能。第四步如果还是不行用telnet 127.0.0.1 8080测连通性或者临时关掉防火墙的内网拦截试一次确认是不是本机防火墙在拦。根因统计下来端口冲突占一半控制台窗口被关占三成剩下的是数据库没初始化成功。数据库没起来这种情况多半是安装时磁盘空间不足或者路径里有中文和空格——安装路径千万不要带中文和空格这是很多人踩过的坑。4.2 本机正常、公网地址空白区分映射故障与内容故障现象本机访问完全正常但点开 Cpolar 生成的公网地址要么一直加载要么报 502要么显示一个空白页。这条链路的关键是先分层到底是请求没到本机还是请求到了但内容不对。判断方法很朴素打开映射的同时本机浏览器也打开一次看本机这一侧有没有访问日志。有日志说明请求进来了问题在内容层没日志说明请求卡在映射层。映射层的问题八成是本地端口填错。回到管理界面检查那条规则的本地端口字段和netstat看到的监听端口对一遍。次常见的原因是填了localhost而不是127.0.0.1同样是 IPv6 解析的锅。内容层的问题常见的是页面里引用了内网地址。打开浏览器开发者工具的网络面板看请求是不是在往127.0.0.1或者内网 IP 上发。如果是说明系统里的站点地址配置还停在本地需要进后台把访问地址改成公网域名。4.3 登录页能开、提交后跳回内网地址这是最典型的一类也是我花时间最多的一次。现象公网地址打开登录页没问题输入账号密码点登录页面跳转之后地址栏变成了http://127.0.0.1:8080/...然后浏览器报无法访问。根因系统内部记录了一个本站点地址所有跳转、资源引用、邮件里的链接都基于这个地址生成。装的时候默认写的是本地地址所以外部访问时跳转就指回了本地。修复进后台找到站点设置那一栏把访问地址改成公网域名保存后清一下缓存再试。改完之后登录跳转、附件下载链接、通知邮件里的链接都会跟着变。同类现象页面能打开但样式全丢白底黑字一堆。这也是资源路径指向内网导致的。按同样的思路修站点地址即可。还有一个小变种登录后一直转圈或者登录成功后刷新又变回未登录。这一般和会话保持有关。先排除浏览器缓存再确认访问的是https还是http两种协议混用会导致会话失效。统一用公网地址访问别一会儿内网一会儿外网混着用必然出问题。4.4 附件上传中断与超大日志文件现象小文件能传几十兆的附件传到一半失败或者上传成功了但别人下载时报错。根因分析附件上传失败通常卡在三个上限上而且是层层递进的关系层级限制项典型默认值表现运行环境层单文件上传上限较小大文件直接被拒运行环境层请求体上限较小上传到一半中断应用层附件大小上限视配置提示超出限制修复顺序应该是先改运行环境再改应用层因为后者依赖前者。运行环境的配置在安装目录下的配置文件里找到上传和请求体相关的两项改大之后必须重启服务才生效。改完一定要重启这是最容易忘的一步——配置改了一年没生效原因就是服务没重启。前端服务器那一层如果还有请求体大小限制也要一起调整否则改了半天还是被挡在前面。还有一个容易忽略的点日志文件会一直涨。系统跑几个月日志目录能涨到几个 G磁盘满了之后所有服务一起挂。解决办法是在后台把日志级别调低一点同时定期清理过期日志文件。我一般加一条计划任务每周清理三十天前的日志。4.5 隔一天再来访问失败地址与会话两件事现象昨天还好好的今天早上同事说打不开了。先查地址有没有变。翻出昨天发出去的链接和现在客户端界面上生成的地址比一下。不一样就是免费方案随机子域名变了。解决办法前面说过申请固定子域名。再查主机关没关机。Windows 机器被自动更新重启、被人误关、休眠没醒这几种都会导致服务下线。系统休眠之后映射进程往往不会自动恢复表现就是地址还在但打不开。处理办法是把电源选项里的休眠和睡眠关掉同时确认电源计划是高性能。最后查映射进程还在不在。客户端是不是还在运行登录状态有没有过期。有些情况下客户端还在但登录态掉了映射就断了重新登录即可。这一类故障的共同点是没有告警。所以我后来加了一个很土但有效的办法在另一个地方放一条定时任务每隔十分钟访问一次公网地址失败就发一条通知。成本几乎为零但能把第二天才知道挂了变成十分钟内知道。5. 从能打开到敢交给同事用的运维清单5.1 开机自启、服务注册与进程守护手动双击启动只适合调试阶段。要真正交付给同事用必须解决机器重启之后谁来把服务拉起来这件事。第一步把 Web 服务和数据库注册成系统服务。一键包通常提供了注册脚本位置在不同版本里略有差异一般在运行环境目录下。注册成功之后打开系统的服务管理器找到对应服务把启动类型改成自动。第二步把映射客户端也设成开机自启。客户端设置里一般有开机启动的开关打开它。有些版本还需要单独设置自动登录否则开机后客户端起来了但没登录映射依然是断的。第三步做一次完整的重启演练。这一步千万别跳过。我见过太多次配置都做了但没人重启过结果真出事那天才发现自启失效。演练的方法是重启机器不登录桌面直接用另一台设备访问公网地址。能打开说明配置成立打不开说明还有环节依赖用户登录。第四步加一层兜底。写一个简单的脚本每隔几分钟检查本地端口是否在监听不在就执行启动命令然后挂到计划任务里。脚本内容大致是echo off netstat -ano | findstr :8080 | findstr LISTENING if errorlevel 1 ( start D:\zentao\start.bat )土归土但它能覆盖服务莫名挂掉这个场景。5.2 备份要演练不能只点按钮备份这件事绝大多数人的问题不是没做而是做了但从没验证过。等到真需要恢复的那天才发现备份文件是空的、或者压缩包损坏、或者根本不知道怎么还原。我的做法是每季度做一次恢复演练。演练流程是找一台闲置机器装一套干净的运行环境把最近一份备份导进去看能不能正常打开、数据对不对。整个过程半小时但能换来真出事时敢动手的底气。备份策略上我会设三档日备系统内置的自动备份每周一次保留四份周备整目录复制到另一块盘保留八份月备整目录复制到移动硬盘或者异地保留三份。三档的意义在于覆盖不同的灾难场景。数据库坏了用日备盘坏了用周备机器没了用月备。备份文件不要和原始数据放在同一块物理盘上这是底线。还有一个细节恢复的时候程序版本最好和备份时一致。跨大版本恢复经常出问题所以我习惯在备份文件名里带上版本号和日期比如zentao-18.5-20250410.zip。5.3 账号、权限与访问准入的最小化系统对外之后账号管理就从随便开变成必须管。我按三条原则来一是管理员不超过两个。一个日常用一个备用。备用账号的密码放在只有负责人知道的地方平时不登录。这条规则的价值在主管理员忘了密码的时候体现得淋漓尽致。二是按角色分配不按人分配。先建角色开发、测试、产品、外部协作再把人塞进角色。这样人员变动的时候只需要改角色成员不用逐个调权限。外部协作方单独建一个角色只给提问题和查看自己提交内容的权限。三是离职即禁用不删除。账号直接删除会导致历史记录里的责任人变成空白追溯就断了。正确做法是停用账号保留数据和历史。另外建议开一个操作日志的习惯定期看一眼有没有异常登录、有没有人批量导出数据。5.4 写一页使用约定比装十个插件有用技术层面搭好之后真正决定这套系统能不能活下去的是使用习惯。我每次交付都会附一页纸的约定内容非常朴素问题标题必须带模块名和现象写成登录页-验证码不刷新不要写有个问题截图必须贴进正文不要只丢在聊天工具里提交时必须选严重程度和所属版本这两个字段后面统计要用关闭问题必须写一句解决说明哪怕是已确认非缺陷每天下班前花两分钟过一遍分配给自己的未关闭问题。这几条看起来繁琐但它们决定了三个月后你拉出来的报表有没有意义。我见过太多实例系统装得很漂亮但所有人提交时标题都写bug最后统计出来一堆无法分类的数据等于白装。还有一个技巧把项目模板配好。禅道里可以预设版本、模块、严重程度的选项配好之后提交表单会变得非常好填人的抵触感会明显下降。这一步花十分钟回报比任何技术优化都高。最后分享一个我自己的体会。这套方案里技术部分其实只占了整个工作量的一小部分真正花时间的是让人愿意用。我最早搭的那套系统功能配置得很全字段加了一堆结果三个月后活跃用户只剩两个。后来我把它砍到只剩标题、描述、严重程度、负责人四个必填项使用率立刻上来了。所以如果你准备动手建议第一版做得越简单越好先把问题有地方记这件事跑通等大家习惯了再慢慢加流程和字段。另外那个固定子域名的钱真的不要省它换来的不只是地址不变还有所有人对这套系统靠谱的第一印象。