拓冰网站定制 
“Manage 的安装与配置”这个题目看着朴素没有任何花哨的定语但真正动手做过的人都知道它背后藏着的是一整套环境治理的活儿。我手上常年维护四套环境本地开发机、联调测试、预发、生产每一套都要跑 JDK、Node、Maven、MySQL、Redis、Nginx 这一长串东西。以前的做法是写一份文档新人照着装装到最后总有一两个版本对不上排查半天。后来我把这套流程收敛到了一个自托管的 Manage 平台上装一次、纳管一片“安装与配置”这件事从大半天压缩到了四十分钟左右。这篇不讲虚的从选型、依赖安装、目录规划到配置文件里每一行到底是干什么的再到我实际踩过的坑全部摊开写。适合两类人看一类是第一次接手这套东西、需要一份能照着抄的清单的人另一类是已经装上了、但配置总出问题、想搞清楚“为什么这么配”的人。哪怕你之前只装过 JDK 和 MySQL跟着走也不会卡住。1. Manage 是什么先把定位说清楚1.1 从“散装环境”说起在没有统一平台之前团队的开发环境基本处于“散装”状态。每个人机器上 JDK 的版本不一样有人是 1.8有人是 11还有人图新装了 17Node 更乱nvm 里挂了三四个版本node -v一敲出来五花八门Maven 的本地仓库路径各写各的settings.xml里的镜像地址全凭个人喜好。这种状态在小项目上还能忍一旦进入多人协作问题就会集中爆发。我印象最深的一次事故是这样的联调环境上跑得好好的构建脚本挪到测试服务器上直接报UnsupportedClassVersionError。查了半天原因是编译机用的是 JDK 11测试服务器上是 JDK 8class 文件的主版本号对不上。这类问题的可怕之处在于它不会在你写代码的时候暴露而是等到打包部署那一刻才炸排查成本极高。第二类高发问题是路径写死某个脚本里硬编码了/home/zhangsan/node/bin/npm换个人执行立刻找不到命令。第三类就是权限混乱服务用 root 跑日志目录谁都能写一次误操作把数据目录删了。散装环境的本质问题是没有单一事实来源。每台机器上的环境都是“历史遗留”没人能准确说出当前线上到底跑的是哪个版本。Manage 要解决的就是这件事把散落的运行时、服务、配置收敛到一个有统一视图的地方。1.2 Manage 的四个核心模块从部署结构上看Manage 一般拆成四块理解这四块的分工后面安装配置才不会晕。模块运行形态主要职责依赖控制台 Web静态资源由 Nginx 托管提供界面发起所有操作浏览器即可服务端 ServerJava 进程监听 8080业务逻辑、调度、鉴权、APIJDK 17、MySQL、RedisAgent轻量常驻进程装在被纳管机器上采集状态、执行下发的指令仅需基础运行环境存储层MySQL Redis 本地工作区元数据、缓存、构建产物磁盘空间控制台只负责“看和点”真正的脏活累活在 Server 和 Agent 里。这个分层设计很关键Server 挂了被纳管机器上的服务该跑还是跑只是看不到实时状态Agent 挂了Server 上会显示离线但不会影响已有业务。很多人第一次装的时候把 Agent 和 Server 装在同一台机器上图省事这在小规模场景下没问题但要知道这俩是独立进程日志也是分开的排查的时候别混在一起看。1.3 什么情况别折腾自建说句实在话不是所有团队都需要自建一套 Manage。以下三种情况我建议直接放弃自建单人开发、没有多环境诉求直接本地装好 JDK 和 Node 就行团队规模小于三人且不做持续交付用现成的托管方案更省心纯前端小项目一个 Node 加一个静态服务器就够了引入 Manage 属于杀鸡用牛刀。自建真正划算的临界点大概在“有三个以上环境 五个人以上 每周至少两次交付”这个量级。到了这个规模环境不一致带来的返工成本会远远超过一次部署投入的两三天时间。我自己这套平台上线之后最直观的收益是新人入职上手时间从一天变成了一小时以及“我这里能跑你那里跑不了”这句话彻底消失了。2. 安装前的准备选型、依赖与目录规划2.1 操作系统与硬件门槛操作系统方面Ubuntu 22.04 LTS 和 CentOS 7.9 我都跑过表现稳定。选 LTS 版本的理由很简单软件源里的 JDK、Nginx 版本相对新且长期有安全更新不用自己去编译。如果你的环境是 CentOS 7要注意它的默认glibc版本偏老装 Node 20 的时候建议用官方二进制包而不是源码编译能省掉一堆兼容问题。硬件配置上我给一个实测过的基线4 核 8G 内存、100G 系统盘。这个配置能支撑大约 20 台被纳管机器、日常几十个构建任务。内存主要吃在两块JVM 堆和 MySQL 的缓冲池8G 是舒服的起点4G 会很紧张。磁盘之所以建议 100G是因为工作区会存放构建产物和日志增长速度快得超出预期我见过一个中等规模团队三个月攒了 40G 的构建缓存。如果预算允许把工作区单独挂一块盘后期扩容和迁移都会轻松很多。网络方面Server 需要能主动访问被纳管机器的 Agent 端口通常是内网的 9100。如果跨网段提前把安全组和防火墙规则理清楚否则会出现“Agent 显示在线但下发指令超时”这种很别扭的现象。这个坑我在第一次部署时踩过当时以为是 Agent 有 bug查了两个小时才发现是中间一层防火墙拦了回包。2.2 依赖组件版本对照表版本选择是安装配置里最容易被忽略、又最容易出问题的一环。下面这张表是我当前生产环境实际在用的版本组合经过了半年多运行验证。组件推荐版本最低可用版本选择理由JDK17 LTS11服务端基于 Spring Boot 3.x强制要求 17 起Node.js20 LTS18前端用 Vite 5 构建要求 18 以上Maven3.9.63.6.33.9 起对 HTTPS 镜像源支持更完整MySQL8.0.355.7.30需要窗口函数且默认字符集必须是 utf8mb4Redis7.26.26.2 起支持 ACL能更细粒度控制权限Nginx1.241.18稳定分支try_files行为可预期Git2.402.20Agent 拉取仓库需要较新的协议支持这里要特别强调 JDK 版本。很多人的机器上预装了 1.8装完 Manage 启动直接报类版本错误。判断方法很直接java -version看一眼。如果显示1.8.0_xxx别犹豫装一个 17 并存用JAVA_HOME切换不要试图卸载系统自带的 1.8有些系统组件会依赖它。MySQL 的字符集也值得单独说。Manage 里存的是多语言混合内容包括机器主机名、项目描述、构建日志片段如果库的字符集是utf8MySQL 里的utf8其实是三字节的残缺实现存四字节字符时会直接报错或者截断。建库时必须显式指定utf8mb4这个后面初始化环节我会给完整命令。2.3 目录结构与运行账号设计目录规划这件事装机的时候花十分钟后面能省下无数次找文件的痛苦。我用的结构是这样的路径用途建议属主/opt/manage/server服务端程序与 jar 包manage/opt/manage/web前端构建产物manage/opt/manage/config所有配置文件集中存放manage/opt/manage/data工作区、构建产物、临时文件manage/opt/manage/logs应用日志manage/opt/runtimeJDK、Node、Maven 等运行时root把配置文件单独拎出来放在config目录是我强烈建议的做法。原因是升级的时候你只需要替换server和web两个目录配置完全不用动。很多人图省事把配置写在 jar 包同级的application.yml升级时一覆盖配置全没了只能凭记忆重写一遍。运行账号方面绝对不要用 root 跑服务。创建一个专用系统账号sudo useradd -r -m -d /opt/manage -s /sbin/nologin manage sudo chown -R manage:manage /opt/manage-r表示创建系统账号-s /sbin/nologin表示禁止登录 shell。这样即使服务被攻破攻击者拿到的也只是个无法登录的受限账号横向移动难度大增。运行时目录/opt/runtime保持 root 属主、755 权限普通用户只读避免被篡改。注意创建完账号后务必检查/opt/manage/data的属主。我遇到过因为工作区是 root 属主导致服务启动时无法写入报了一个非常隐晦的Permission denied日志里只显示“初始化工作区失败”完全没有提示是权限问题。3. Manage 本体安装从依赖到跑起来3.1 基础依赖安装实操先装 JDK。Ubuntu 系列最省事的方式是走包管理sudo apt update sudo apt install -y openjdk-17-jdk java -version如果系统源里的版本不够新或者你用的是 CentOS建议用官方压缩包手动部署路径可控性更好sudo mkdir -p /opt/runtime sudo tar -zxvf jdk-17.0.9_linux-x64_bin.tar.gz -C /opt/runtime/ sudo mv /opt/runtime/jdk-17.0.9 /opt/runtime/jdk17环境变量不要直接写进/etc/profile那个文件内容多、容易改坏。单独放一个 profile 片段更清爽sudo tee /etc/profile.d/manage-runtime.sh EOF export JAVA_HOME/opt/runtime/jdk17 export MAVEN_HOME/opt/runtime/maven export NODE_HOME/opt/runtime/node20 export PATH$JAVA_HOME/bin:$MAVEN_HOME/bin:$NODE_HOME/bin:$PATH EOF sudo chmod x /etc/profile.d/manage-runtime.sh source /etc/profile.d/manage-runtime.sh这种写法的好处是后续新增运行时比如再加个 Gradle只需要往这个文件里追加一行不用去动系统文件。Node 20 直接用二进制包解压即可比装 nvm 更适合服务器场景因为服务器上通常不需要频繁切版本sudo tar -xJf node-v20.11.0-linux-x64.tar.xz -C /opt/runtime/ sudo mv /opt/runtime/node-v20.11.0-linux-x64 /opt/runtime/node20 node -v npm -vMaven 装完一定要改settings.xml否则构建时从默认中央仓库拉依赖会慢到让人怀疑人生。配置文件放在$MAVEN_HOME/conf/settings.xml重点改两处localRepository指向一个独立大盘路径mirror换成内网或就近的镜像源。本地仓库单独放的理由是它会长到几十 G放在系统盘迟早把盘撑满。3.2 数据库与缓存的初始化MySQL 安装完成后第一件事是建库建账号。这里给出我用了很久的标准语句CREATE DATABASE manage DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER manage127.0.0.1 IDENTIFIED BY StrongPass_2024; GRANT ALL PRIVILEGES ON manage.* TO manage127.0.0.1; FLUSH PRIVILEGES;注意主机名部分写的是127.0.0.1而不是%。服务端和数据库在同一台机器上时限定来源能有效防止误连。如果数据库独立部署就换成服务端的内网 IP。用%是很多人的习惯但它的含义是“允许任意来源”在安全上是明显减分的。字符集和排序规则要写全utf8mb4_general_ci在绝大多数场景下够用如果对多语言排序有严格要求的场景换成utf8mb4_0900_ai_ci。另外记得调整连接数上限Manage 在并发构建时会开不少连接# /etc/mysql/mysql.conf.d/mysqld.cnf max_connections 500 innodb_buffer_pool_size 2Ginnodb_buffer_pool_size设成物理内存的 25% 到 40% 是个经验值。8G 内存的机器给 2G 比较稳妥给太多会和 JVM 抢内存反而拖慢整体。Redis 这边安装后重点改三处配置sudo sed -i s/^# requirepass .*/requirepass StrongRedisPass_2024/ /etc/redis/redis.conf sudo sed -i s/^bind 127.0.0.1 ::1/bind 127.0.0.1/ /etc/redis/redis.conf第一处设密码第二处限制只监听本机。第三处是持久化策略默认的 RDB 可能丢数据改成 AOF 更稳妥代价是磁盘写入增加。Manage 里 Redis 主要存会话和任务队列丢失会导致用户被踢下线、任务重跑不算致命但能避免就避免。3.3 服务端的打包与启动进入server目录用 Maven 打包。第一次打包建议跳过测试速度快很多cd /opt/manage/server mvn clean package -DskipTests -T 1C-T 1C表示按 CPU 核数并行构建四核机器上能把打包时间压掉大约一半这是我实测有效的参数。打包完成后产物在target/下把它挪到固定位置cp target/manage-server.jar /opt/manage/server/manage-server.jar启动方式有两种。手动调试阶段直接命令行起方便看日志sudo -u manage /opt/runtime/jdk17/bin/java \ -jar /opt/manage/server/manage-server.jar \ --spring.config.location/opt/manage/config/application.yml生产环境必须用 systemd 托管否则进程一崩就没人拉起来。配置文件写到/etc/systemd/system/manage.service[Unit] DescriptionManage Server Afternetwork.target mysql.service redis-server.service [Service] Usermanage Groupmanage WorkingDirectory/opt/manage/server EnvironmentMANAGE_DB_PASSWORDStrongPass_2024 EnvironmentMANAGE_REDIS_PASSWORDStrongRedisPass_2024 ExecStart/opt/runtime/jdk17/bin/java -Xms1g -Xmx2g -XX:UseG1GC -jar /opt/manage/server/manage-server.jar --spring.config.location/opt/manage/config/application.yml Restartalways RestartSec10 LimitNOFILE65535 [Install] WantedBymulti-user.target这段配置里有几个细节值得解释。密码通过Environment注入而不是写进配置文件是为了让配置文件可以进版本库而不泄露敏感信息配合配置里的${MANAGE_DB_PASSWORD}占位符生效。LimitNOFILE65535是必须的Manage 会维持大量长连接默认的 1024 文件句柄很快就不够用表现是间歇性的连接失败。-Xms和-Xmx设成一样避免堆在运行期间反复伸缩带来的抖动。启用并启动sudo systemctl daemon-reload sudo systemctl enable manage sudo systemctl start manage sudo systemctl status manage3.4 前端构建与反向代理前端用 Node 构建依赖安装一定要用npm ci而不是npm install。前者的行为由 lock 文件严格决定能保证每次构建产物完全一致后者会去更新依赖埋下隐患。cd /opt/manage/web-src npm ci npm run build sudo cp -r dist/* /opt/manage/web/ sudo chown -R manage:manage /opt/manage/web构建完之后用 Nginx 做静态托管和 API 反向代理。这个配置是整个安装里最关键也最容易配错的一环server { listen 80; server_name manage.internal.example.com; root /opt/manage/web; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_read_timeout 300s; } location /ws/ { proxy_pass http://127.0.0.1:8080/ws/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; } }try_files那一行是前端单页应用的标准写法作用是访问任何前端路由都返回index.html由前端自己决定渲染哪个页面。少了这一行页面刷新就会 404。proxy_read_timeout 300s是针对构建任务调大超时默认 60 秒会把长时间运行的构建请求直接掐断。WebSocket 那段是给实时日志推送用的Connection upgrade必须写成带引号的形式不加引号 Nginx 会报语法错误这是个很隐蔽的坑。3.5 冒烟测试与首次登录服务起来之后别急着打开浏览器先用命令行做三轮验证。第一轮验证服务端活着curl -s http://127.0.0.1:8080/actuator/health # 期望输出{status:UP}第二轮验证数据库连通看日志里有没有连接池初始化失败的报错tail -n 100 /opt/manage/logs/manage-server.log | grep -i hikari\|datasource第三轮验证 Nginx 转发通curl -s -o /dev/null -w %{http_code}\n http://manage.internal.example.com/api/actuator/health # 期望输出200三轮都过了再打开浏览器。首次登录通常使用默认管理员账号登录后第一件事就是改密码别拖。我见过有人装完忘了改两个月后才发现有人从外网扫到了这个端口虽然最后没造成损失但那种后背发凉的感觉不值得体验第二次。4. 配置详解每一个参数到底在干什么4.1 服务端核心配置逐段拆解配置文件是整个系统的大脑这里给出一份完整示例然后逐段解释。server: port: 8080 shutdown: graceful tomcat: threads: max: 200 min-spare: 20 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/manage?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltruerewriteBatchedStatementstrue username: manage password: ${MANAGE_DB_PASSWORD} hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 max-lifetime: 1200000 redis: host: 127.0.0.1 port: 6379 password: ${MANAGE_REDIS_PASSWORD} database: 0 timeout: 3000 manage: workspace: /opt/manage/data agent: port: 9100 token: ${MANAGE_AGENT_TOKEN} heartbeat-interval: 30 offline-threshold: 90 build: max-concurrent: 4 timeout: 1800shutdown: graceful这一行很容易被忽略但价值很高。它的作用是收到停止信号时先把手上的请求处理完再退出而不是一刀切断。在升级场景下这一行能避免正在构建的任务被强行中断。tomcat.threads.max: 200是给 Web 请求准备的线程数4 核机器上设 200 已经比较宽裕设太大反而增加上下文切换开销。JDBC 连接串里有三个参数值得单说。serverTimezoneAsia/Shanghai不加会导致时间字段存进去差 8 小时这是 Java 连 MySQL 8 的经典问题。allowPublicKeyRetrievaltrue是 MySQL 8 默认使用caching_sha2_password认证插件时的必需项不加会报认证失败。rewriteBatchedStatementstrue能让批量插入性能提升好几倍Manage 在批量写入机器状态时会用到。Hikari 连接池的max-lifetime: 1200000表示连接最长存活 20 分钟。这个值必须小于 MySQL 的wait_timeout否则会出现连接被数据库单方面关闭、应用还在用的情况报错是Communications link failure。MySQL 默认wait_timeout是 28800 秒所以 20 分钟是安全的。4.2 Agent 配置与纳管接入Agent 的配置比服务端简单但 token 和心跳两个参数必须理解清楚。token是 Agent 向 Server 证明身份的凭证两边必须完全一致。生成方式建议用随机字符串openssl rand -hex 32把这个值同时填进服务端的MANAGE_AGENT_TOKEN和每台被纳管机器的 Agent 配置里通过环境变量注入不要明文写在文件里。heartbeat-interval: 30表示 Agent 每 30 秒上报一次状态offline-threshold: 90表示连续 90 秒没上报就标记为离线。这两个值的关系是阈值至少要是间隔的 2.5 倍否则网络稍有抖动就会误报离线运维群里天天响告警。Agent 侧还有一个容易忽略的配置项采集范围。默认会采集 CPU、内存、磁盘、进程数如果你的机器上跑着敏感进程可以通过白名单限制只上报指定进程。这个配置在合规要求高的环境里是必选项。4.3 数据源、缓存与存储配置工作区workspace的路径规划有个细节一定要和备份策略对齐。因为这个目录里存着构建产物、临时文件和日志是磁盘增长的主要来源。我建议按workspace/builds、workspace/tmp、workspace/artifacts三个子目录分开方便针对性地做清理策略。构建产物可以设保留最近 30 天的清理规则临时文件每次任务结束就删产物目录按业务重要性单独决定。Redis 的database: 0表示用 0 号库。如果同一台 Redis 上还跑着别的应用一定要分库否则会互相干扰。判断方法是在配置里搜一下有没有别的地方也用database: 0。这个坑我踩过Manage 的会话数据被另一个应用清库操作一起冲掉了用户集体掉线查了半天才定位到是共用了同一个库。4.4 安全配置别把控制台裸在外面安全这块我列四条底线按重要性排序首次登录立刻改密码并且开启强密码策略长度至少 12 位含大小写、数字、符号。关闭注册入口。自建平台的用户应该由管理员创建公开注册等于给陌生人开门。不要直接把 8080 暴露到公网。所有流量走 Nginx服务端只监听127.0.0.1在application.yml里把server.address设成127.0.0.1。开启操作审计。谁在什么时候对哪台机器下发了什么命令必须有完整记录。出了事这是唯一能追溯的依据。如果平台需要跨公网访问务必套一层 HTTPS。内网自建可以用内部 CA 签发证书不必强求公有证书。配置上就是在 Nginx 的 server 块里加 443 监听和证书路径同时把 80 端口的请求 301 跳转过去。5. 常见故障与排查实录5.1 启动阶段五类高发故障这五类问题基本覆盖了我遇到过的所有“起不来”场景按发生频率排序。第一类是端口占用。现象是启动日志里出现Address already in use。定位命令很直接sudo ss -lntp | grep -E 8080|9100|3306|6379找到占用进程后先判断它是不是旧版本的 Manage 没退干净是的话kill掉重启即可。第二类是数据库连不上。表现形式多样日志里可能是Access denied也可能是Unknown database还可能是长时间卡住后超时。按顺序排查账号密码对不对、库存不存在、bind-address有没有限制来源、防火墙规则通不通。我常用的排查命令是直接用命令行客户端连一遍把应用层的问题剥掉mysql -h 127.0.0.1 -P 3306 -u manage -p manage -e SELECT 1;第三类是 JDK 版本不符。报错是UnsupportedClassVersionError错误信息里会带上具体的版本号比如class file version 61.0。61 对应 JDK 17如果你的 java 是 1.8 就会报这个。解决方法是用绝对路径启动别依赖 PATH。第四类是工作区权限。前面提过症状是日志只写一句含糊的初始化失败。排查方法sudo -u manage touch /opt/manage/data/.test rm /opt/manage/data/.test用服务账号亲自试一下写权限比看日志快得多。第五类是 Redis 认证失败。日志里的关键词是NOAUTH Authentication required或者WRONGPASS。前者说明配置里没填密码后者说明密码填错了。改完配置记得systemctl restart manage改了配置不重启是我见过最高频的低级失误。5.2 排查速查表把上面这些经验整理成一张表遇到问题直接对照现象可能原因定位命令处理方式启动即退出无异常堆栈配置文件路径不对journalctl -u manage -n 50检查--spring.config.location健康检查返回 DOWN数据库或 Redis 不通curl 127.0.0.1:8080/actuator/health看 health 详情里的组件状态页面能开但接口 502Nginx 转发地址错tail -f /var/log/nginx/error.log核对proxy_pass端口刷新页面 404缺try_files直接看 Nginx 配置补上try_files $uri $uri/ /index.htmlAgent 显示在线但超时回包被防火墙拦telnet 被纳管IP 9100放通双向 9100构建任务卡住不动并发数设太低看max-concurrent配置调到 CPU 核数时间显示差 8 小时缺时区参数看 JDBC URL加serverTimezoneAsia/Shanghai日志文件涨到几十 G没配轮转du -sh /opt/manage/logs配logrotate这张表里的每一条都是我实际撞过的尤其是时间差 8 小时那条第一次遇到的时候我盯着数据库里的时间戳看了很久怀疑是服务器时区没设对结果问题出在 JDBC 连接串上。5.3 上线后的稳定性调优服务跑起来只是第一步让它稳得住需要做一些调优。我把实际生效的几项列出来。JVM 方面G1 垃圾回收器配上-XX:MaxGCPauseMillis200是比较通用的组合。如果堆内存超过 4G可以考虑上 ZGC停顿时间能压到毫秒级代价是内存占用略高。生产环境的堆大小建议不超过物理内存的一半剩下的留给操作系统页缓存和 MySQL。Nginx 方面worker_processes设成 CPU 核数worker_connections设 10240同时打开sendfile和tcp_nopush。这几项能让静态资源的分发效率明显提升尤其是前端资源包有几兆的时候差别肉眼可见。日志方面必须配轮转否则迟早撑爆磁盘。一个简单的logrotate配置/opt/manage/logs/*.log { daily rotate 14 compress delaycompress missingok notifempty copytruncate }copytruncate这个选项很关键。因为 Java 进程会一直持有日志文件句柄用默认的移动方式会导致进程继续往已删除的文件里写磁盘空间不会释放。加上这个选项日志被截断而不是移动空间能正常回收。注意调完/etc/security/limits.conf里的文件句柄数之后光重启 Manage 是没用的必须重启对应的 systemd 服务因为 systemd 有自己的LimitNOFILE设置会覆盖系统的 limits。这个点卡了我很久最后是在 systemd 单元里显式写LimitNOFILE65535才解决。6. 备份、升级与迁移的实操建议6.1 备份策略三件套缺一不可Manage 的备份要覆盖三样东西数据库、配置文件、工作区。缺任何一样恢复的时候都会缺胳膊少腿。数据库用逻辑备份最稳妥配合定时任务mysqldump -u manage -pStrongPass_2024 \ --single-transaction --routines --triggers \ manage | gzip /backup/manage_$(date %F).sql.gz--single-transaction保证备份期间不锁表业务照常跑。这一点很重要不加的话备份会锁全表赶上业务高峰期直接把平台卡死。配置文件直接打包config目录即可体积小建议每次都全量备份。工作区体积大全量备份不现实只备份artifacts目录下的关键产物就好tmp和builds里的内容可以重建不备份。保留策略上数据库备份留 30 天配置文件留 90 天产物按业务需要决定。备份文件一定要定期做恢复演练我见过备份脚本跑了一年从没报错真出事的时候才发现备份出来的是空文件因为密码改了但脚本里的密码没同步更新。6.2 平滑升级的标准流程升级这件事顺序错了就会造成业务中断。我总结的流程是先停 Agent再备数据然后换包最后起服务。# 1. 在被纳管机器上暂停 Agent避免升级期间下发指令 sudo systemctl stop manage-agent # 2. 备份 sudo systemctl stop manage mysqldump ... /backup/pre_upgrade.sql tar -czf /backup/config_$(date %F).tar.gz /opt/manage/config # 3. 替换程序与前端产物 sudo cp manage-server-new.jar /opt/manage/server/manage-server.jar sudo cp -r dist-new/* /opt/manage/web/ # 4. 执行数据库变更脚本如果有 mysql -u manage -p manage upgrade_v2.3_to_v2.4.sql # 5. 启动并验证 sudo systemctl start manage curl -s http://127.0.0.1:8080/actuator/health # 6. 恢复 Agent sudo systemctl start manage-agent先停 Agent 这个顺序很多人会搞反。如果不停 Agent升级过程中 Server 可能会给老版本 Agent 下发新格式的指令Agent 解析不了就会报错日志里一堆异常虽然不影响最终结果但排查起来很干扰。6.3 迁移到新机器的注意事项迁移时最容易翻车的不是数据本身而是那些“配置之外的隐性依赖”。我踩过的有忘记把 Agent 的 token 带过去导致所有机器显示离线忘记调整workspace路径新机器上目录不存在忘了把 JVM 参数一起迁移性能莫名其妙下降一截。建议的做法是把所有非默认配置整理成一份清单迁移时逐项核对。清单至少包括数据库连接串、Redis 地址与密码、Agent token、工作区路径、并发数、JVM 参数、Nginx 配置。整理一次之后后续每次迁移都能复用不会再漏。另外一个建议是迁移完成后先在一台非关键机器上做全流程验证确认纳管、构建、日志查看都正常再逐步放开其余机器。一上来全量切换出问题时影响面太大恢复也慢。最后分享一个我一直在用的习惯每次环境有变动无论是改了配置、升了版本还是调了参数都在config目录下开一个CHANGELOG.md写清楚时间、改了什么、为什么改。这东西看起来是额外负担但等到三个月后出了问题回头查“当时为什么把这个参数调成 4”这种问题翻记录十秒钟就能有答案比自己回忆靠谱得多。 Manage 安装与配置实战：环境治理、依赖版本与故障排查
“Manage 的安装与配置”这个题目看着朴素没有任何花哨的定语但真正动手做过的人都知道它背后藏着的是一整套环境治理的活儿。我手上常年维护四套环境本地开发机、联调测试、预发、生产每一套都要跑 JDK、Node、Maven、MySQL、Redis、Nginx 这一长串东西。以前的做法是写一份文档新人照着装装到最后总有一两个版本对不上排查半天。后来我把这套流程收敛到了一个自托管的 Manage 平台上装一次、纳管一片“安装与配置”这件事从大半天压缩到了四十分钟左右。这篇不讲虚的从选型、依赖安装、目录规划到配置文件里每一行到底是干什么的再到我实际踩过的坑全部摊开写。适合两类人看一类是第一次接手这套东西、需要一份能照着抄的清单的人另一类是已经装上了、但配置总出问题、想搞清楚“为什么这么配”的人。哪怕你之前只装过 JDK 和 MySQL跟着走也不会卡住。1. Manage 是什么先把定位说清楚1.1 从“散装环境”说起在没有统一平台之前团队的开发环境基本处于“散装”状态。每个人机器上 JDK 的版本不一样有人是 1.8有人是 11还有人图新装了 17Node 更乱nvm 里挂了三四个版本node -v一敲出来五花八门Maven 的本地仓库路径各写各的settings.xml里的镜像地址全凭个人喜好。这种状态在小项目上还能忍一旦进入多人协作问题就会集中爆发。我印象最深的一次事故是这样的联调环境上跑得好好的构建脚本挪到测试服务器上直接报UnsupportedClassVersionError。查了半天原因是编译机用的是 JDK 11测试服务器上是 JDK 8class 文件的主版本号对不上。这类问题的可怕之处在于它不会在你写代码的时候暴露而是等到打包部署那一刻才炸排查成本极高。第二类高发问题是路径写死某个脚本里硬编码了/home/zhangsan/node/bin/npm换个人执行立刻找不到命令。第三类就是权限混乱服务用 root 跑日志目录谁都能写一次误操作把数据目录删了。散装环境的本质问题是没有单一事实来源。每台机器上的环境都是“历史遗留”没人能准确说出当前线上到底跑的是哪个版本。Manage 要解决的就是这件事把散落的运行时、服务、配置收敛到一个有统一视图的地方。1.2 Manage 的四个核心模块从部署结构上看Manage 一般拆成四块理解这四块的分工后面安装配置才不会晕。模块运行形态主要职责依赖控制台 Web静态资源由 Nginx 托管提供界面发起所有操作浏览器即可服务端 ServerJava 进程监听 8080业务逻辑、调度、鉴权、APIJDK 17、MySQL、RedisAgent轻量常驻进程装在被纳管机器上采集状态、执行下发的指令仅需基础运行环境存储层MySQL Redis 本地工作区元数据、缓存、构建产物磁盘空间控制台只负责“看和点”真正的脏活累活在 Server 和 Agent 里。这个分层设计很关键Server 挂了被纳管机器上的服务该跑还是跑只是看不到实时状态Agent 挂了Server 上会显示离线但不会影响已有业务。很多人第一次装的时候把 Agent 和 Server 装在同一台机器上图省事这在小规模场景下没问题但要知道这俩是独立进程日志也是分开的排查的时候别混在一起看。1.3 什么情况别折腾自建说句实在话不是所有团队都需要自建一套 Manage。以下三种情况我建议直接放弃自建单人开发、没有多环境诉求直接本地装好 JDK 和 Node 就行团队规模小于三人且不做持续交付用现成的托管方案更省心纯前端小项目一个 Node 加一个静态服务器就够了引入 Manage 属于杀鸡用牛刀。自建真正划算的临界点大概在“有三个以上环境 五个人以上 每周至少两次交付”这个量级。到了这个规模环境不一致带来的返工成本会远远超过一次部署投入的两三天时间。我自己这套平台上线之后最直观的收益是新人入职上手时间从一天变成了一小时以及“我这里能跑你那里跑不了”这句话彻底消失了。2. 安装前的准备选型、依赖与目录规划2.1 操作系统与硬件门槛操作系统方面Ubuntu 22.04 LTS 和 CentOS 7.9 我都跑过表现稳定。选 LTS 版本的理由很简单软件源里的 JDK、Nginx 版本相对新且长期有安全更新不用自己去编译。如果你的环境是 CentOS 7要注意它的默认glibc版本偏老装 Node 20 的时候建议用官方二进制包而不是源码编译能省掉一堆兼容问题。硬件配置上我给一个实测过的基线4 核 8G 内存、100G 系统盘。这个配置能支撑大约 20 台被纳管机器、日常几十个构建任务。内存主要吃在两块JVM 堆和 MySQL 的缓冲池8G 是舒服的起点4G 会很紧张。磁盘之所以建议 100G是因为工作区会存放构建产物和日志增长速度快得超出预期我见过一个中等规模团队三个月攒了 40G 的构建缓存。如果预算允许把工作区单独挂一块盘后期扩容和迁移都会轻松很多。网络方面Server 需要能主动访问被纳管机器的 Agent 端口通常是内网的 9100。如果跨网段提前把安全组和防火墙规则理清楚否则会出现“Agent 显示在线但下发指令超时”这种很别扭的现象。这个坑我在第一次部署时踩过当时以为是 Agent 有 bug查了两个小时才发现是中间一层防火墙拦了回包。2.2 依赖组件版本对照表版本选择是安装配置里最容易被忽略、又最容易出问题的一环。下面这张表是我当前生产环境实际在用的版本组合经过了半年多运行验证。组件推荐版本最低可用版本选择理由JDK17 LTS11服务端基于 Spring Boot 3.x强制要求 17 起Node.js20 LTS18前端用 Vite 5 构建要求 18 以上Maven3.9.63.6.33.9 起对 HTTPS 镜像源支持更完整MySQL8.0.355.7.30需要窗口函数且默认字符集必须是 utf8mb4Redis7.26.26.2 起支持 ACL能更细粒度控制权限Nginx1.241.18稳定分支try_files行为可预期Git2.402.20Agent 拉取仓库需要较新的协议支持这里要特别强调 JDK 版本。很多人的机器上预装了 1.8装完 Manage 启动直接报类版本错误。判断方法很直接java -version看一眼。如果显示1.8.0_xxx别犹豫装一个 17 并存用JAVA_HOME切换不要试图卸载系统自带的 1.8有些系统组件会依赖它。MySQL 的字符集也值得单独说。Manage 里存的是多语言混合内容包括机器主机名、项目描述、构建日志片段如果库的字符集是utf8MySQL 里的utf8其实是三字节的残缺实现存四字节字符时会直接报错或者截断。建库时必须显式指定utf8mb4这个后面初始化环节我会给完整命令。2.3 目录结构与运行账号设计目录规划这件事装机的时候花十分钟后面能省下无数次找文件的痛苦。我用的结构是这样的路径用途建议属主/opt/manage/server服务端程序与 jar 包manage/opt/manage/web前端构建产物manage/opt/manage/config所有配置文件集中存放manage/opt/manage/data工作区、构建产物、临时文件manage/opt/manage/logs应用日志manage/opt/runtimeJDK、Node、Maven 等运行时root把配置文件单独拎出来放在config目录是我强烈建议的做法。原因是升级的时候你只需要替换server和web两个目录配置完全不用动。很多人图省事把配置写在 jar 包同级的application.yml升级时一覆盖配置全没了只能凭记忆重写一遍。运行账号方面绝对不要用 root 跑服务。创建一个专用系统账号sudo useradd -r -m -d /opt/manage -s /sbin/nologin manage sudo chown -R manage:manage /opt/manage-r表示创建系统账号-s /sbin/nologin表示禁止登录 shell。这样即使服务被攻破攻击者拿到的也只是个无法登录的受限账号横向移动难度大增。运行时目录/opt/runtime保持 root 属主、755 权限普通用户只读避免被篡改。注意创建完账号后务必检查/opt/manage/data的属主。我遇到过因为工作区是 root 属主导致服务启动时无法写入报了一个非常隐晦的Permission denied日志里只显示“初始化工作区失败”完全没有提示是权限问题。3. Manage 本体安装从依赖到跑起来3.1 基础依赖安装实操先装 JDK。Ubuntu 系列最省事的方式是走包管理sudo apt update sudo apt install -y openjdk-17-jdk java -version如果系统源里的版本不够新或者你用的是 CentOS建议用官方压缩包手动部署路径可控性更好sudo mkdir -p /opt/runtime sudo tar -zxvf jdk-17.0.9_linux-x64_bin.tar.gz -C /opt/runtime/ sudo mv /opt/runtime/jdk-17.0.9 /opt/runtime/jdk17环境变量不要直接写进/etc/profile那个文件内容多、容易改坏。单独放一个 profile 片段更清爽sudo tee /etc/profile.d/manage-runtime.sh EOF export JAVA_HOME/opt/runtime/jdk17 export MAVEN_HOME/opt/runtime/maven export NODE_HOME/opt/runtime/node20 export PATH$JAVA_HOME/bin:$MAVEN_HOME/bin:$NODE_HOME/bin:$PATH EOF sudo chmod x /etc/profile.d/manage-runtime.sh source /etc/profile.d/manage-runtime.sh这种写法的好处是后续新增运行时比如再加个 Gradle只需要往这个文件里追加一行不用去动系统文件。Node 20 直接用二进制包解压即可比装 nvm 更适合服务器场景因为服务器上通常不需要频繁切版本sudo tar -xJf node-v20.11.0-linux-x64.tar.xz -C /opt/runtime/ sudo mv /opt/runtime/node-v20.11.0-linux-x64 /opt/runtime/node20 node -v npm -vMaven 装完一定要改settings.xml否则构建时从默认中央仓库拉依赖会慢到让人怀疑人生。配置文件放在$MAVEN_HOME/conf/settings.xml重点改两处localRepository指向一个独立大盘路径mirror换成内网或就近的镜像源。本地仓库单独放的理由是它会长到几十 G放在系统盘迟早把盘撑满。3.2 数据库与缓存的初始化MySQL 安装完成后第一件事是建库建账号。这里给出我用了很久的标准语句CREATE DATABASE manage DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER manage127.0.0.1 IDENTIFIED BY StrongPass_2024; GRANT ALL PRIVILEGES ON manage.* TO manage127.0.0.1; FLUSH PRIVILEGES;注意主机名部分写的是127.0.0.1而不是%。服务端和数据库在同一台机器上时限定来源能有效防止误连。如果数据库独立部署就换成服务端的内网 IP。用%是很多人的习惯但它的含义是“允许任意来源”在安全上是明显减分的。字符集和排序规则要写全utf8mb4_general_ci在绝大多数场景下够用如果对多语言排序有严格要求的场景换成utf8mb4_0900_ai_ci。另外记得调整连接数上限Manage 在并发构建时会开不少连接# /etc/mysql/mysql.conf.d/mysqld.cnf max_connections 500 innodb_buffer_pool_size 2Ginnodb_buffer_pool_size设成物理内存的 25% 到 40% 是个经验值。8G 内存的机器给 2G 比较稳妥给太多会和 JVM 抢内存反而拖慢整体。Redis 这边安装后重点改三处配置sudo sed -i s/^# requirepass .*/requirepass StrongRedisPass_2024/ /etc/redis/redis.conf sudo sed -i s/^bind 127.0.0.1 ::1/bind 127.0.0.1/ /etc/redis/redis.conf第一处设密码第二处限制只监听本机。第三处是持久化策略默认的 RDB 可能丢数据改成 AOF 更稳妥代价是磁盘写入增加。Manage 里 Redis 主要存会话和任务队列丢失会导致用户被踢下线、任务重跑不算致命但能避免就避免。3.3 服务端的打包与启动进入server目录用 Maven 打包。第一次打包建议跳过测试速度快很多cd /opt/manage/server mvn clean package -DskipTests -T 1C-T 1C表示按 CPU 核数并行构建四核机器上能把打包时间压掉大约一半这是我实测有效的参数。打包完成后产物在target/下把它挪到固定位置cp target/manage-server.jar /opt/manage/server/manage-server.jar启动方式有两种。手动调试阶段直接命令行起方便看日志sudo -u manage /opt/runtime/jdk17/bin/java \ -jar /opt/manage/server/manage-server.jar \ --spring.config.location/opt/manage/config/application.yml生产环境必须用 systemd 托管否则进程一崩就没人拉起来。配置文件写到/etc/systemd/system/manage.service[Unit] DescriptionManage Server Afternetwork.target mysql.service redis-server.service [Service] Usermanage Groupmanage WorkingDirectory/opt/manage/server EnvironmentMANAGE_DB_PASSWORDStrongPass_2024 EnvironmentMANAGE_REDIS_PASSWORDStrongRedisPass_2024 ExecStart/opt/runtime/jdk17/bin/java -Xms1g -Xmx2g -XX:UseG1GC -jar /opt/manage/server/manage-server.jar --spring.config.location/opt/manage/config/application.yml Restartalways RestartSec10 LimitNOFILE65535 [Install] WantedBymulti-user.target这段配置里有几个细节值得解释。密码通过Environment注入而不是写进配置文件是为了让配置文件可以进版本库而不泄露敏感信息配合配置里的${MANAGE_DB_PASSWORD}占位符生效。LimitNOFILE65535是必须的Manage 会维持大量长连接默认的 1024 文件句柄很快就不够用表现是间歇性的连接失败。-Xms和-Xmx设成一样避免堆在运行期间反复伸缩带来的抖动。启用并启动sudo systemctl daemon-reload sudo systemctl enable manage sudo systemctl start manage sudo systemctl status manage3.4 前端构建与反向代理前端用 Node 构建依赖安装一定要用npm ci而不是npm install。前者的行为由 lock 文件严格决定能保证每次构建产物完全一致后者会去更新依赖埋下隐患。cd /opt/manage/web-src npm ci npm run build sudo cp -r dist/* /opt/manage/web/ sudo chown -R manage:manage /opt/manage/web构建完之后用 Nginx 做静态托管和 API 反向代理。这个配置是整个安装里最关键也最容易配错的一环server { listen 80; server_name manage.internal.example.com; root /opt/manage/web; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_read_timeout 300s; } location /ws/ { proxy_pass http://127.0.0.1:8080/ws/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; } }try_files那一行是前端单页应用的标准写法作用是访问任何前端路由都返回index.html由前端自己决定渲染哪个页面。少了这一行页面刷新就会 404。proxy_read_timeout 300s是针对构建任务调大超时默认 60 秒会把长时间运行的构建请求直接掐断。WebSocket 那段是给实时日志推送用的Connection upgrade必须写成带引号的形式不加引号 Nginx 会报语法错误这是个很隐蔽的坑。3.5 冒烟测试与首次登录服务起来之后别急着打开浏览器先用命令行做三轮验证。第一轮验证服务端活着curl -s http://127.0.0.1:8080/actuator/health # 期望输出{status:UP}第二轮验证数据库连通看日志里有没有连接池初始化失败的报错tail -n 100 /opt/manage/logs/manage-server.log | grep -i hikari\|datasource第三轮验证 Nginx 转发通curl -s -o /dev/null -w %{http_code}\n http://manage.internal.example.com/api/actuator/health # 期望输出200三轮都过了再打开浏览器。首次登录通常使用默认管理员账号登录后第一件事就是改密码别拖。我见过有人装完忘了改两个月后才发现有人从外网扫到了这个端口虽然最后没造成损失但那种后背发凉的感觉不值得体验第二次。4. 配置详解每一个参数到底在干什么4.1 服务端核心配置逐段拆解配置文件是整个系统的大脑这里给出一份完整示例然后逐段解释。server: port: 8080 shutdown: graceful tomcat: threads: max: 200 min-spare: 20 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/manage?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltruerewriteBatchedStatementstrue username: manage password: ${MANAGE_DB_PASSWORD} hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 max-lifetime: 1200000 redis: host: 127.0.0.1 port: 6379 password: ${MANAGE_REDIS_PASSWORD} database: 0 timeout: 3000 manage: workspace: /opt/manage/data agent: port: 9100 token: ${MANAGE_AGENT_TOKEN} heartbeat-interval: 30 offline-threshold: 90 build: max-concurrent: 4 timeout: 1800shutdown: graceful这一行很容易被忽略但价值很高。它的作用是收到停止信号时先把手上的请求处理完再退出而不是一刀切断。在升级场景下这一行能避免正在构建的任务被强行中断。tomcat.threads.max: 200是给 Web 请求准备的线程数4 核机器上设 200 已经比较宽裕设太大反而增加上下文切换开销。JDBC 连接串里有三个参数值得单说。serverTimezoneAsia/Shanghai不加会导致时间字段存进去差 8 小时这是 Java 连 MySQL 8 的经典问题。allowPublicKeyRetrievaltrue是 MySQL 8 默认使用caching_sha2_password认证插件时的必需项不加会报认证失败。rewriteBatchedStatementstrue能让批量插入性能提升好几倍Manage 在批量写入机器状态时会用到。Hikari 连接池的max-lifetime: 1200000表示连接最长存活 20 分钟。这个值必须小于 MySQL 的wait_timeout否则会出现连接被数据库单方面关闭、应用还在用的情况报错是Communications link failure。MySQL 默认wait_timeout是 28800 秒所以 20 分钟是安全的。4.2 Agent 配置与纳管接入Agent 的配置比服务端简单但 token 和心跳两个参数必须理解清楚。token是 Agent 向 Server 证明身份的凭证两边必须完全一致。生成方式建议用随机字符串openssl rand -hex 32把这个值同时填进服务端的MANAGE_AGENT_TOKEN和每台被纳管机器的 Agent 配置里通过环境变量注入不要明文写在文件里。heartbeat-interval: 30表示 Agent 每 30 秒上报一次状态offline-threshold: 90表示连续 90 秒没上报就标记为离线。这两个值的关系是阈值至少要是间隔的 2.5 倍否则网络稍有抖动就会误报离线运维群里天天响告警。Agent 侧还有一个容易忽略的配置项采集范围。默认会采集 CPU、内存、磁盘、进程数如果你的机器上跑着敏感进程可以通过白名单限制只上报指定进程。这个配置在合规要求高的环境里是必选项。4.3 数据源、缓存与存储配置工作区workspace的路径规划有个细节一定要和备份策略对齐。因为这个目录里存着构建产物、临时文件和日志是磁盘增长的主要来源。我建议按workspace/builds、workspace/tmp、workspace/artifacts三个子目录分开方便针对性地做清理策略。构建产物可以设保留最近 30 天的清理规则临时文件每次任务结束就删产物目录按业务重要性单独决定。Redis 的database: 0表示用 0 号库。如果同一台 Redis 上还跑着别的应用一定要分库否则会互相干扰。判断方法是在配置里搜一下有没有别的地方也用database: 0。这个坑我踩过Manage 的会话数据被另一个应用清库操作一起冲掉了用户集体掉线查了半天才定位到是共用了同一个库。4.4 安全配置别把控制台裸在外面安全这块我列四条底线按重要性排序首次登录立刻改密码并且开启强密码策略长度至少 12 位含大小写、数字、符号。关闭注册入口。自建平台的用户应该由管理员创建公开注册等于给陌生人开门。不要直接把 8080 暴露到公网。所有流量走 Nginx服务端只监听127.0.0.1在application.yml里把server.address设成127.0.0.1。开启操作审计。谁在什么时候对哪台机器下发了什么命令必须有完整记录。出了事这是唯一能追溯的依据。如果平台需要跨公网访问务必套一层 HTTPS。内网自建可以用内部 CA 签发证书不必强求公有证书。配置上就是在 Nginx 的 server 块里加 443 监听和证书路径同时把 80 端口的请求 301 跳转过去。5. 常见故障与排查实录5.1 启动阶段五类高发故障这五类问题基本覆盖了我遇到过的所有“起不来”场景按发生频率排序。第一类是端口占用。现象是启动日志里出现Address already in use。定位命令很直接sudo ss -lntp | grep -E 8080|9100|3306|6379找到占用进程后先判断它是不是旧版本的 Manage 没退干净是的话kill掉重启即可。第二类是数据库连不上。表现形式多样日志里可能是Access denied也可能是Unknown database还可能是长时间卡住后超时。按顺序排查账号密码对不对、库存不存在、bind-address有没有限制来源、防火墙规则通不通。我常用的排查命令是直接用命令行客户端连一遍把应用层的问题剥掉mysql -h 127.0.0.1 -P 3306 -u manage -p manage -e SELECT 1;第三类是 JDK 版本不符。报错是UnsupportedClassVersionError错误信息里会带上具体的版本号比如class file version 61.0。61 对应 JDK 17如果你的 java 是 1.8 就会报这个。解决方法是用绝对路径启动别依赖 PATH。第四类是工作区权限。前面提过症状是日志只写一句含糊的初始化失败。排查方法sudo -u manage touch /opt/manage/data/.test rm /opt/manage/data/.test用服务账号亲自试一下写权限比看日志快得多。第五类是 Redis 认证失败。日志里的关键词是NOAUTH Authentication required或者WRONGPASS。前者说明配置里没填密码后者说明密码填错了。改完配置记得systemctl restart manage改了配置不重启是我见过最高频的低级失误。5.2 排查速查表把上面这些经验整理成一张表遇到问题直接对照现象可能原因定位命令处理方式启动即退出无异常堆栈配置文件路径不对journalctl -u manage -n 50检查--spring.config.location健康检查返回 DOWN数据库或 Redis 不通curl 127.0.0.1:8080/actuator/health看 health 详情里的组件状态页面能开但接口 502Nginx 转发地址错tail -f /var/log/nginx/error.log核对proxy_pass端口刷新页面 404缺try_files直接看 Nginx 配置补上try_files $uri $uri/ /index.htmlAgent 显示在线但超时回包被防火墙拦telnet 被纳管IP 9100放通双向 9100构建任务卡住不动并发数设太低看max-concurrent配置调到 CPU 核数时间显示差 8 小时缺时区参数看 JDBC URL加serverTimezoneAsia/Shanghai日志文件涨到几十 G没配轮转du -sh /opt/manage/logs配logrotate这张表里的每一条都是我实际撞过的尤其是时间差 8 小时那条第一次遇到的时候我盯着数据库里的时间戳看了很久怀疑是服务器时区没设对结果问题出在 JDBC 连接串上。5.3 上线后的稳定性调优服务跑起来只是第一步让它稳得住需要做一些调优。我把实际生效的几项列出来。JVM 方面G1 垃圾回收器配上-XX:MaxGCPauseMillis200是比较通用的组合。如果堆内存超过 4G可以考虑上 ZGC停顿时间能压到毫秒级代价是内存占用略高。生产环境的堆大小建议不超过物理内存的一半剩下的留给操作系统页缓存和 MySQL。Nginx 方面worker_processes设成 CPU 核数worker_connections设 10240同时打开sendfile和tcp_nopush。这几项能让静态资源的分发效率明显提升尤其是前端资源包有几兆的时候差别肉眼可见。日志方面必须配轮转否则迟早撑爆磁盘。一个简单的logrotate配置/opt/manage/logs/*.log { daily rotate 14 compress delaycompress missingok notifempty copytruncate }copytruncate这个选项很关键。因为 Java 进程会一直持有日志文件句柄用默认的移动方式会导致进程继续往已删除的文件里写磁盘空间不会释放。加上这个选项日志被截断而不是移动空间能正常回收。注意调完/etc/security/limits.conf里的文件句柄数之后光重启 Manage 是没用的必须重启对应的 systemd 服务因为 systemd 有自己的LimitNOFILE设置会覆盖系统的 limits。这个点卡了我很久最后是在 systemd 单元里显式写LimitNOFILE65535才解决。6. 备份、升级与迁移的实操建议6.1 备份策略三件套缺一不可Manage 的备份要覆盖三样东西数据库、配置文件、工作区。缺任何一样恢复的时候都会缺胳膊少腿。数据库用逻辑备份最稳妥配合定时任务mysqldump -u manage -pStrongPass_2024 \ --single-transaction --routines --triggers \ manage | gzip /backup/manage_$(date %F).sql.gz--single-transaction保证备份期间不锁表业务照常跑。这一点很重要不加的话备份会锁全表赶上业务高峰期直接把平台卡死。配置文件直接打包config目录即可体积小建议每次都全量备份。工作区体积大全量备份不现实只备份artifacts目录下的关键产物就好tmp和builds里的内容可以重建不备份。保留策略上数据库备份留 30 天配置文件留 90 天产物按业务需要决定。备份文件一定要定期做恢复演练我见过备份脚本跑了一年从没报错真出事的时候才发现备份出来的是空文件因为密码改了但脚本里的密码没同步更新。6.2 平滑升级的标准流程升级这件事顺序错了就会造成业务中断。我总结的流程是先停 Agent再备数据然后换包最后起服务。# 1. 在被纳管机器上暂停 Agent避免升级期间下发指令 sudo systemctl stop manage-agent # 2. 备份 sudo systemctl stop manage mysqldump ... /backup/pre_upgrade.sql tar -czf /backup/config_$(date %F).tar.gz /opt/manage/config # 3. 替换程序与前端产物 sudo cp manage-server-new.jar /opt/manage/server/manage-server.jar sudo cp -r dist-new/* /opt/manage/web/ # 4. 执行数据库变更脚本如果有 mysql -u manage -p manage upgrade_v2.3_to_v2.4.sql # 5. 启动并验证 sudo systemctl start manage curl -s http://127.0.0.1:8080/actuator/health # 6. 恢复 Agent sudo systemctl start manage-agent先停 Agent 这个顺序很多人会搞反。如果不停 Agent升级过程中 Server 可能会给老版本 Agent 下发新格式的指令Agent 解析不了就会报错日志里一堆异常虽然不影响最终结果但排查起来很干扰。6.3 迁移到新机器的注意事项迁移时最容易翻车的不是数据本身而是那些“配置之外的隐性依赖”。我踩过的有忘记把 Agent 的 token 带过去导致所有机器显示离线忘记调整workspace路径新机器上目录不存在忘了把 JVM 参数一起迁移性能莫名其妙下降一截。建议的做法是把所有非默认配置整理成一份清单迁移时逐项核对。清单至少包括数据库连接串、Redis 地址与密码、Agent token、工作区路径、并发数、JVM 参数、Nginx 配置。整理一次之后后续每次迁移都能复用不会再漏。另外一个建议是迁移完成后先在一台非关键机器上做全流程验证确认纳管、构建、日志查看都正常再逐步放开其余机器。一上来全量切换出问题时影响面太大恢复也慢。最后分享一个我一直在用的习惯每次环境有变动无论是改了配置、升了版本还是调了参数都在config目录下开一个CHANGELOG.md写清楚时间、改了什么、为什么改。这东西看起来是额外负担但等到三个月后出了问题回头查“当时为什么把这个参数调成 4”这种问题翻记录十秒钟就能有答案比自己回忆靠谱得多。