1. 先弄清楚ecology9这台机器由哪些零件组成1.1 从入职第一天那句你先把系统跑起来说起入职第一天下午Leader 扔过来一句话本地 Windows 环境先搭一套 ecology9把功能点摸一遍别急着看代码。当时的我对着压缩包愣了大概十分钟——ecology9 这类协同办公平台从来不是双击安装包一路下一步就完事的软件它更像一台拼装出来的整机数据库、缓存、检索引擎、Java 运行环境、中间件少一个零件都启动不起来。这篇文章记录的就是我在 Windows 上从零到登录首页跑通 ecology9 的全过程包括踩过的坑和后来复盘时觉得早该这么干的细节。本地部署 ecology9 这件事说难不难说简单也真不简单关键是要先搞懂它的零件清单和彼此之间的依赖关系不然你会在各种报错日志里绕圈子。本文适合三类人刚接触 ecology9 的运维和交付同学、需要本地复现问题的开发同学以及想在自己电脑上搭一套协同办公系统练手的技术爱好者。所有操作都基于 Windows 10/11 或 Windows Server 环境思路同样可以迁移到其他 Java 系协同平台。1.2 ecology9的组件拓扑与本地最小可用集ecology9 是典型的 Java 单体应用加外围依赖的架构。它自己跑在中间件里业务数据落库会话和热点数据放缓存全文检索单独走一个检索引擎附件和上传文件落在磁盘目录上。这四块是骨架剩下的邮件、短信、消息推送、单点登录之类本地练习阶段可以全部先放着不管。先把零件清单列清楚心里有个底组件作用本地最小可用配置常见坑JDKecology9 的运行基础JDK 8部分版本支持 11以交付包文档为准装了两个 JDK环境变量指向了错的那个数据库存业务数据和配置MySQL 8.0 或 SQL Server 2016字符集不对导入脚本报错中间件承载应用Resin 或 Tomcat端口冲突、JVM 参数没配缓存会话、验证码、锁Redis 3.x 及以上Windows 上的 Redis 版本太老命令不兼容检索引擎全文检索、附件内容搜索Elasticsearch 单节点内存给太小启动直接被系统杀掉文件目录附件、模板、日志普通本地磁盘目录路径带空格或中文导致上传失败这里要强调一句不要一上来就照着某个终极教程把所有组件都装上。先确认你手上交付包里附带的《部署手册》或《环境要求说明》里面会写清楚这个版本支持哪些 JDK、哪些数据库版本。ecology9 的不同小版本之间对 Elasticsearch 和 Redis 的版本要求是有差异的这一点我在后面会再展开。1.3 为什么我坚持先在Windows本地搭一遍有同事问过我为什么不直接连测试环境改代码非要折腾本地这一套。我的理由有三点都是实打实吃过亏之后总结出来的。第一本地环境完全受你控制日志级别想调到 DEBUG 就调到 DEBUG数据库里的数据想删就删不用担心影响别人。第二ecology9 的很多问题只在首次初始化阶段暴露比如脚本执行顺序、字符集、驱动版本这些在已经跑起来的测试环境里根本看不出来。第三本地跑通一遍之后你对这套系统的启动链路会有肌肉记忆以后再遇到线上问题光是看日志就能大致判断是卡在哪一环。不过也得说清楚本地环境不等于生产环境。单节点、无集群、无负载均衡性能参数也是够用就行。所以本地部署 ecology9 的目标是功能验证和问题复现不是性能压测。带着这个定位去做你会轻松很多。2. Windows环境地基JDK、数据库、缓存、检索四件套2.1 操作系统与硬件资源的现实评估先说硬件。很多人栽的第一个跟头不是配置写错而是机器压根带不动。ecology9 加上 Elasticsearch光 Java 进程就是两个大内存消耗户再加上数据库16GB 内存的笔记本是起步线32GB 会舒服很多。我实测下来在 16GB 的机器上如果同时开着 IDE 和浏览器十几个标签页系统会开始频繁换页启动速度肉眼可见地变慢。我建议按下面的方式分配内存这是一套在 16GB 单机上验证过、能稳定跑通 ecology9 的方案。总内存 16GB 的分配方案操作系统与常用软件留 3GBMySQL 给 3GB其中innodb_buffer_pool_size设 1GB 到 2GBRedis 给 512MB 到 1GBElasticsearch 的 JVM 堆给 2GB-Xms2g -Xmx2g中间件里的 ecology9 应用堆给 4GB剩下的留作系统缓存和突发开销。这里有个容易忽略的点Elasticsearch 的堆内存不要超过物理内存的一半官方文档里反复强调过堆给太大反而会因为 GC 停顿和无法使用文件系统缓存而变慢。我在第一次配置时给 ES 分了 4GB结果中间件就没内存用了启动到一半直接 OutOfMemory排查了快两个小时才反应过来是资源分配的问题。如果是 32GB 的机器可以把 MySQL 提到 6GB、ES 堆提到 4GB、应用堆提到 8GB整体会宽裕不少。磁盘方面建议预留 50GB 以上的空闲空间因为数据库文件、ES 索引、日志和附件目录加起来会增长得比你想的快。2.2 JDK选型安装与环境变量JDK 版本这块务必以交付包附带文档为准。ecology9 主流版本跑在 JDK 8 上选 Oracle JDK 8 或者 OpenJDK 8 的稳定发行版都可以。安装时我有两个习惯一是安装路径不要带空格和中文比如装到D:\env\jdk1.8这种位置很多 Java 应用在读路径时对空格处理得并不友好二是不要装完就完事一定要把JAVA_HOME和PATH配好并验证。:: 以管理员身份打开命令提示符设置系统级环境变量 setx JAVA_HOME D:\env\jdk1.8 /M setx PATH %PATH%;%JAVA_HOME%\bin /M :: 重新打开一个命令行窗口再验证setx 不会影响当前会话 java -version javac -version echo %JAVA_HOME%注意设置完环境变量后必须重新开一个命令行窗口setx只对新会话生效这是新手最容易困惑的地方——明明配置成功了java -version却还是老版本。另外提醒一句如果你的机器上已经装了多个 JDK检查一下PATH里排在前面的是哪一个。我见过最典型的故障是命令行里java -version显示 8但中间件启动脚本里写死了另一个 JDK 的路径结果应用用的是 11然后一堆诡异的类加载错误。2.3 数据库选型与MySQL 8的落地细节数据库选型主要看你的交付包和团队习惯。三种常见选择的对比如下数据库优势本地部署注意点适合场景MySQL 8.0安装轻、资料多、社区活跃默认字符集已是 utf8mb4驱动要用 8.x个人练手、小型项目SQL Server与部分生态组件兼容性好安装包大、占用资源多已有 SQL Server 使用习惯的团队Oracle稳定、功能完整安装配置复杂、资源占用高客户指定 Oracle 的交付场景我本地选的是 MySQL 8.0理由很简单装起来快出问题好查。安装时用 MySQL 官方的安装器选择 Server only 就行把 root 密码设好并记牢。装完之后建议做两件事一是把my.ini里的character-set-server确认为utf8mb4二是把max_allowed_packet调到 64M 以上。第二点很多人会忽略但是在导入 ecology9 的初始化脚本时会直接卡住——脚本里有几条大 INSERT包大小不够就会报 Packet for query is too large。# my.ini 关键片段 [mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_general_ci max_allowed_packet64M innodb_buffer_pool_size1G innodb_log_file_size256M default-time-zone08:00时区那一行也是我踩过坑之后加上的。ecology9 里不少时间字段依赖数据库时区如果数据库用的是 UTC 而应用按东八区解析新建的流程、日程时间会整体偏移几个小时而且这种问题在前端看起来非常隐蔽你会以为是代码 bug。数据库客户端工具我建议备一个可视化工具Navicat、DBeaver、MySQL Workbench 都可以本地开发阶段用社区版或者免费工具完全够用别在这上面浪费时间。2.4 Redis在Windows上的可用方案Redis 官方并不提供 Windows 版本这是很多人第一次在 Windows 上部署生态应用时的一个认知盲区。三种可行路子一是用社区保留的 Windows 编译版本版本偏老但对本地开发够用二是用支持 Windows 的 Redis 兼容服务三是在 WSL 里跑官方 Redis通过端口映射供 Windows 侧访问。我本地图省事用的是社区编译版解压后在目录里执行启动命令即可。:: 在 Redis 解压目录下执行 redis-server.exe redis.windows.conf :: 另开一个窗口验证连通性 redis-cli.exe -h 127.0.0.1 -p 6379 127.0.0.1:6379 ping PONG生态应用连接 Redis 的配置项通常在数据库配置附近的文件里一般包含地址、端口、密码、库索引。把maxmemory设成 512MB 到 1GB策略用allkeys-lru就行本地环境不用纠结淘汰策略的细节。这里有个细节值得注意如果你的 ecology9 版本会往 Redis 里写会话务必开启持久化或者干脆接受重启后需要重新登录这个事实别去关掉 RDB 又指望重启后数据还在。2.5 Elasticsearch本地单节点的启动要点Elasticsearch 是这套环境里最容易启动失败的组件。首次启动前要改两个文件config/elasticsearch.yml和config/jvm.options。# config/elasticsearch.yml 本地单节点最小配置 cluster.name: ecology-local node.name: node-1 network.host: 127.0.0.1 http.port: 9200 discovery.type: single-node# config/jvm.options 堆内存调整改这两行 -Xms2g -Xmx2g用discovery.type: single-node是为了跳过集群发现检查否则单节点启动时会有几十秒的选主等待日志里刷一堆 warning看着很吓人。堆内存前面已经说过不要超过物理内存的一半。注意新版 Elasticsearch 默认开启了安全认证本地开发如果只想快速跑通可以在配置文件里把安全相关开关关掉但记住这只适用于本机调试任何对外提供服务的环境都必须开启认证。启动方式是在bin目录下执行elasticsearch.bat第一次启动会比较慢等日志里出现 started 字样后再用浏览器访问http://127.0.0.1:9200能看到 JSON 格式的节点信息就说明成功了。如果启动到一半窗口直接消失多半是内存不够被系统终止了去看logs目录下的日志文件里面会写清楚原因。3. 目录规划与数据库初始化3.1 一套不容易返工的目录结构我强烈建议在动手之前先把目录结构规划好否则等你装到一半想挪位置配置文件里的路径改起来能改到你怀疑人生。我的目录规划是这样的D:\env放所有中间件包括 JDK、Redis、Elasticsearch、数据库D:\ecology放 ecology9 的应用包和附件目录D:\ecology\logs单独放日志D:\ecology\files放附件和上传文件。这么分的好处是需要备份时直接打包D:\ecology就行中间件不需要备份需要清理日志时也不会误删应用文件。另外所有路径都用纯英文加数字不要出现中文和空格。我见过因为附件目录带了中文路径导致用户上传附件成功但下载时 404 的案例排查了半天才发现是路径编码问题。3.2 建库语句与字符集参数建库这一步看着简单但字符集和排序规则选错了后面导入脚本时会以各种奇怪的方式失败。我的建库语句是这样的CREATE DATABASE ecology9 DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_general_ci; -- 单独建一个账号比直接用 root 更贴近真实环境 CREATE USER ecology% IDENTIFIED BY YourStrongPassword; GRANT ALL PRIVILEGES ON ecology9.* TO ecology%; FLUSH PRIVILEGES;为什么用utf8mb4而不是utf8因为utf8在 MySQL 里其实是不完整的三字节实现存不了表情符号和部分生僻字用户姓名、审批意见里一旦出现这类字符就会插入失败或者变成问号。用utf8mb4_general_ci做排序规则是为了兼容性utf8mb4_0900_ai_ci在 MySQL 8 里是默认值但部分生态组件的脚本对它有兼容性顾虑用 general_ci 更保险。3.3 初始化SQL脚本的执行顺序与坑初始化脚本一般放在交付包的db或sql目录下可能是单个大 SQL 文件也可能是分模块的多个文件。执行之前先看一眼文件头和命名规则通常会有类似1_xxx.sql、2_xxx.sql的编号按编号顺序执行。我用命令行导入比图形化工具更可靠mysql -u ecology -p --default-character-setutf8mb4 ecology9 D:\ecology\db\1_init.sql三个要点一是必须指定--default-character-setutf8mb4否则会按系统默认字符集解析中文注释和初始数据会乱码二是导入过程中不要中断大文件导入可能要几分钟三是导入完成后确认一下关键表有没有数据比如用户表、菜单表、系统参数表。我遇到的第一个大坑就在这里。第一次导入时没加字符集参数导入过程没有报错但登录页面能打开、登录却一直提示账号密码错误。后来发现初始管理员的密码在导入时就已经乱码了数据库里存的哈希值自然对不上。重新建库、带字符集参数重新导入之后问题消失。所以凡是遇到脚本导入成功但功能异常的情况第一反应就应该是去查字符集。4. 应用侧部署中间件配置与配置文件逐项拆解4.1 中间件选型Resin与Tomcat各自的适用场景ecology9 常见两种部署方式使用泛微配套的 Resin或者部署到标准 Tomcat 上。两者各有适用场景。中间件优点需要留意的地方Resin与产品适配度高官方文档和客服都熟悉配置文件语法与 Tomcat 不同遇到问题资料少Tomcat通用性强、社区资料多、调试方便部分产品特性需要额外配置才能完全对齐如果是本地学习我建议用交付包里推荐的中间件因为很多产品层面的行为比如某些静态资源处理、类加载顺序在配套中间件上已经调好了换中间件可能引入不必要的变量。只有在需要跟生产环境保持一致、或者团队有统一规范时才考虑换另外一套。这一点我先说明白下面给出的配置是通用性写法具体文件名和语法请以你手上交付包的说明为准。4.2 部署包解压与目录一览把应用包解压到D:\ecology之后先花两分钟扫一遍目录大致是这么几块WEB-INF下放配置和类文件WEB-INF\prop放各种属性配置WEB-INF\lib放依赖包还有前端静态资源目录和附件存放目录。熟悉这些目录的位置后面改配置、看日志、清缓存都靠它。有几类目录我建议提前认识清楚logs目录下按日期滚动生成日志文件出问题第一时间看最新的那个prop目录下的属性文件是连接数据库、Redis、检索服务的核心配置classbean或类似目录下可能有自定义的扩展配置。还有人会把WEB-INF\lib里的 jar 包版本搞混尤其是数据库驱动直接复制一个高版本驱动进去结果应用启动时报驱动方法找不到。4.3 weaver.properties关键配置项逐条说明数据库、Redis 的连接配置基本都在这类属性文件里。下面是常见配置项和我一般怎么填# 数据库连接 ecology.urljdbc:mysql://127.0.0.1:3306/ecology9?useUnicodetruecharacterEncodingutf8mb4serverTimezoneAsia/ShanghaiuseSSLfalse ecology.usernameecology ecology.passwordYourStrongPassword ecology.drivercom.mysql.cj.jdbc.Driver # 连接池 ecology.initialSize5 ecology.minIdle5 ecology.maxActive50 ecology.maxWait60000 ecology.validationQuerySELECT 1 # Redis redis.host127.0.0.1 redis.port6379 redis.password redis.database0 # 附件与文件目录 ecology.file.pathD:/ecology/files逐条说几个关键点。连接串里的serverTimezoneAsia/Shanghai必须加前面提过时区问题这个参数是 MySQL 8 驱动的强制要求之一不加会报时区无法识别的异常。useSSLfalse是本地环境关掉 SSL 握手省掉证书相关的报错。驱动类要看你的驱动版本MySQL 8 用com.mysql.cj.jdbc.Driver5.x 用com.mysql.jdbc.Driver写错了启动时直接报 ClassNotFound。连接池的maxActive不要设得特别大。本地单机环境下 50 个连接足够设到几百反而容易把数据库的连接数耗尽。validationQuery的作用是检测连接是否存活避免拿到已经断开的连接去执行 SQL。注意属性文件里路径统一用正斜杠/不要用反斜杠\。Java 读属性文件时反斜杠是转义字符D:\ecology\files会被解析成乱码路径这是很多人附件目录配了却不起作用的根本原因。4.4 启动参数与内存分配的计算过程启动参数这块我习惯把堆内存、垃圾回收和编码三件事固定下来。以 16GB 机器、应用堆 4GB 为例:: 中间件启动脚本中的 JVM 参数 set JAVA_OPTS-Xms4096m -Xmx4096m -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m ^ -XX:UseG1GC -XX:MaxGCPauseMillis200 ^ -Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8 ^ -Duser.timezoneAsia/Shanghai-Xms和-Xmx设成一样是为了避免运行过程中堆反复扩容收缩带来的性能抖动这在本地开发时体感很明显。MetaspaceSize给 256m 起步因为 ecology9 这类应用加载的类非常多元空间不够会在启动完成后的一段时间内频繁触发 Full GC。用 G1 收集器并把最大停顿目标放在 200ms是兼顾吞吐和响应比较稳妥的选择。编码参数一定要显式写上。Windows 默认编码是 GBK如果 Java 进程按默认编码读取配置文件中文会乱码日志里的中文也会变成问号。user.timezone同理不指定的话 Windows 上取到的时区可能不是你期望的那个。5. 首次启动从日志到登录页的验证链路5.1 启动脚本与日志观察启动方式很简单进入中间件的bin目录执行启动脚本然后盯着控制台和日志文件看。判断启动是否成功不要只看最后一行有没有异常而是要按顺序确认几件事JVM 是否正常起来了、数据源是否初始化成功、Redis 连接是否建立、应用上下文是否加载完成、监听端口是否开始监听。:: 在中间件 bin 目录下 startup.bat :: 观察日志示例具体文件名按实际调整 type D:\ecology\logs\ecology.log我一般会用tail的思路去看最新的日志尾部Windows 上可以用 PowerShell 的Get-Content -Wait命令持续跟踪。启动过程中最值得关注的是数据库连接池初始化和上下文加载完成这两条记录它们出现之后基本就成功一大半了。Get-Content D:\ecology\logs\ecology.log -Wait -Tail 505.2 系统初始化向导与管理员账号第一次访问系统时一般会进入初始化配置流程接受许可、检查环境、创建管理员账号、设置系统基本信息。这一步有几个点要留意。管理员账号和密码要记好尤其是密码ecology9 的密码策略通常要求包含大小写字母、数字和特殊字符如果随手设一个简单密码后面系统会提示不合规。系统名称、logo、首页风格这些可以先随便填本地练习不需要纠结品牌信息。初始化过程中如果卡住不动最常见的原因是检索引擎没起来或者连接配置不对。因为初始化阶段会重建索引如果 ES 地址配错了页面会一直转圈日志里能看到连接超时的堆栈。这时候别急着重装先去prop目录检查检索引擎的配置项改完重启应用即可数据库里的数据不用动。5.3 上线前的功能验证清单本地环境跑起来之后别急着开始改代码。我建议按下面这张清单把核心链路走一遍确认环境是干净可用的不然你后面写的所有 bug 都可能是环境问题导致的验证项操作通过标准登录用管理员账号登录能进首页左上角显示用户名用户管理新建一个测试用户列表能看到新用户能编辑保存组织架构新建部门并把用户挂进去树形结构正确显示流程发起找一个简单流程发起申请能提交并进入待办流程审批用审批人账号处理后提交状态流转正确有流转记录附件上传在文档或流程里上传附件上传成功且能下载打开全文检索搜索刚上传的文档里的文字能搜到结果日志查看系统日志模块有操作记录产生这八项里只要全文检索能搜到刚上传的附件内容说明数据库、应用、检索引擎三个环节都是通的这一步能省掉后面大量到底是哪里出的问题的排查工作。6. 踩坑记录本地部署高频故障与排查思路6.1 启动阶段端口、编码、驱动启动阶段的问题最集中我按发生频率排个序。排第一的是端口冲突检索引擎、缓存、数据库、中间件、应用本身都要占用端口如果电脑上已经跑着别的服务很可能撞车。排查方法是启动前先看一眼报错日志里的端口号然后用netstat -ano | findstr 端口号找到占用进程。第二个高频问题是编码。除了前面说的属性文件路径反斜杠、数据库字符集还有一个容易忽略的点Windows 控制台默认是 GBK 编码如果启动脚本里没设置chcp 65001控制台输出的中文日志会乱码虽然不影响运行但看日志时非常痛苦。第三个是驱动版本。MySQL 驱动包和数据库版本之间存在兼容矩阵把 8.x 的驱动放到期望 5.x 的应用里或者反过来都会报奇怪的错误。我一般把驱动 jar 包的名字和版本号跟数据库版本对一遍再放进去。6.2 运行阶段附件、检索、定时任务应用跑起来之后的坑更有隐蔽性。附件相关的问题主要集中在路径和权限上路径配错会导致上传后找不到文件目录没有写权限会导致上传直接失败。检查方法很直接手动往附件目录里写一个文件能写进去说明权限没问题。检索相关的问题通常是索引没同步。表现是数据明明存在但搜索搜不到。解决思路是先确认检索服务健康状态再在系统后台找到重建索引的入口重新建一次索引。如果重建索引耗时特别长往往是数据量或者分片配置的问题本地环境可以把分片数调小。定时任务相关的问题会表现为某些数据一直不更新。这类问题要去日志里找我通常称之为任务调度的记录看任务有没有被触发、执行是不是抛了异常。还有一种情况是任务被重复触发同一台机器上启动了两个应用实例或者定时任务开关配重了这些在本地环境也会发生。6.3 一张速查表加三条私藏经验把常见问题整理成一张速查表出问题时按表排查能省不少时间现象可能原因排查动作启动即退出无日志JVM 参数错误或内存不足检查启动脚本、降低堆内存重试启动卡在上下文加载数据库连接失败检查连接串、驱动、网络连通性登录报账号密码错误初始化脚本字符集问题重建库、带 utf8mb4 重新导入页面能开但样式丢失静态资源路径或缓存问题清理浏览器缓存与模板缓存附件上传失败目录路径或写权限问题手动验证目录写权限检查路径分隔符搜索无结果检索服务未连上或索引未建访问检索端口重建索引时间显示偏移数据库或 JVM 时区不一致统一为东八区并重启定时任务不执行调度未启动或任务重复查调度日志确认实例数三条私藏经验。第一条每次改完配置文件先把应用完全停干净再重启别指望热加载很多配置项是启动时一次性读取的。第二条给自己写一个环境快照文档记录 JDK 版本、数据库版本、驱动版本、各组件端口号和目录换机器或重装时能省下大半天。第三条遇到无解的报错先把日志级别调到 DEBUG往往答案就藏在被 INFO 级别过滤掉的那几行里。7. 本地环境跑通之后的调优与维护习惯7.1 让系统跑得更快的几个参数本地环境虽然不追求性能但把几个参数调好开发体验会有明显提升。数据库层面innodb_buffer_pool_size是最关键的一项它决定了多少数据能缓存在内存里本地给到物理内存的 25% 左右比较合适。应用层面把模板缓存开启避免每次请求都重新解析页面模板。检索层面把索引刷新间隔适当放宽牺牲一点实时性换取更低的资源占用。还有一个小细节是日志级别。开发阶段用 INFO 甚至 DEBUG长期跑的时候建议调回 WARN否则日志文件几天就能涨到几个 G。我在本地就遇到过磁盘被日志写满导致应用无法写入临时文件而崩溃的情况后来加了个日志清理脚本才解决。7.2 备份与可回滚的日常习惯最后说一个我个人特别看重、但很多新手容易忽略的习惯在你准备做任何有风险的改动之前先做一次可回滚的快照。具体做法是先把数据库整体导出再把应用目录和附件目录各复制一份打上日期标记。这样哪怕配置改崩了十分钟就能恢复到一个已知可用的状态而不是从头再装一遍。做导出的时候有个小技巧mysqldump记得带上--single-transaction和--default-character-setutf8mb4前者保证导出过程不会锁表后者保证中文不乱码。附件目录如果很大第一次做全量备份之后可以只备份增量变化的部分。我在实际使用中发现本地环境的价值不在于它能跑多少并发而在于它给了你一个可以随便折腾、随时推倒重来的沙盒。第一天把 ecology9 在 Windows 上跑通看起来只是装了几个软件、改了几行配置但这个过程逼着你去理解一套企业级应用是怎么把数据库、缓存、检索、中间件串起来的——这套认知后面在排查线上问题时会反复派上用场。最后再分享一个小技巧把整个部署过程中改过的每一个配置项、遇到的每一个报错都随手记在一个 Markdown 文件里放在项目根目录。等你部署第二套、第三套环境时这个文件就是你自己写给自己的最靠谱的文档。