NCCloud开发环境搭建全攻略：从架构到部署避坑指南

1. 先从搞清楚NCCloud开发环境的技术架构开始做NCCloud开发环境搭建之前我建议你先别急着点下一步、下一步。十年前我拿到第一套NC的安装包时也是一顿操作猛如虎结果数据库连不上、服务起不来、前端页面白屏折腾了两天才发现是版本匹配的问题。NCCloud用友NC Cloud作为面向大中型企业的数字化管控平台本质上不是一个单纯的应用软件而是一整套由前端工程、应用服务、数据库、中间件、缓存和文件服务组成的系统。你要做开发环境搭建第一件事不是装而是把它的架构捋清楚。NCCloud在逻辑上分为四层表现层浏览器或桌面端、接入层Nginx等反向代理、应用服务层NC Cloud服务端通常部署在中间件如TongWeb或WebLogic中、数据层主流关系型数据库。开发环境和一个几百台机器的生产集群当然没法比但它的核心组件一样都不能少。你至少需要准备的组件包括JDK 8部分版本要求64位具体以你拿到的安装包说明为准NCCloud服务端安装包与对应的数据字典/补丁包数据库实例开发阶段选哪个数据库都可以但生产与开发尽量保持一致Redis用于会话共享、缓存部分业务组件强依赖文件存储目录NCCloud的附件、临时文件、日志输出都放在这里Nginx或Apache用于反向代理静态资源解决跨域和端口转发很多同事第一次搭环境时最常犯的错误是把生产环境的部署文档原封不动搬到开发机上非得凑够三台服务器。其实开发环境追求的是最小可用一台性能足够的个人工作站或者虚拟机完全能承载全部组件。我在公司内部一直倡导一个原则开发环境保持简洁但版本流向必须对齐生产。意思就是JDK大版本、数据库主版本、NCCloud小版本这些关键参数要和正式环境一致否则你在本地调通的代码一上测试环境就跑不起来最后排查了半天居然是环境差异这种时间浪费是最冤枉的。我实际搭建时使用的推荐配置如下表你可以根据自己的机器情况调整组件开发机最低要求建议配置说明CPU4核8核及以上NCCloud启动时会做大量类扫描和编译内存8GB16GB及以上中间件数据库Redis前端构建同时跑非常吃内存磁盘200GB可用500GB SSD日志、临时文件、安装包的体积比我预想的大得多操作系统Linux/Windows均可LinuxCentOS 7或Ubuntu 20.04线上多为Linux本地用Linux更贴近生产2. 环境规划与前置准备少走弯路的配置清单2.1 安装目录规划别什么都往系统盘塞这里先讲一个我踩过的坑。第一套NCCloud我装的时候图省事全部用默认路径中间件装在C盘Windows机器数据库也在C盘结果跑了两周C盘爆红系统直接卡死。后来换Linux服务器后我养成了一个习惯——所有组件一律装在独立的、非系统分区的目录下。统一的目录规划不仅能避免磁盘占满的问题还能让备份和灰度发布变得非常方便。我的规划方式如下/data/nccloud/ ├── app # NCCloud服务端安装目录 ├── db # 数据库数据目录 ├── redis # Redis安装目录与数据持久化目录 ├── nginx # Nginx安装目录 ├── files # NCCloud文件存储根目录 ├── logs # 统一日志收集目录 └── backup # 数据库备份、安装包备份目录这套目录结构的好处有两个第一每个组件的日志都能分开收集出问题时不用在一堆默认路径里翻找第二目录权限控制非常清晰比如给NCCloud服务运行账号只授予app和files目录的读写权限避免越权操作。CLOUDBASE_SYSTEM_HOME这个环境变量也需要提前约定好。NCCloud在运行时会往这个目录写配置文件、缓存和临时文件如果没有提前设置它可能落到系统默认的用户目录里权限不足时就会出现一些非常难以定位的报错。我一般都会在配置文件中统一定义到/data/nccloud/config下确保重启服务不会丢配置。2.2 域名与Hosts映射前后端联调的基本盘开发环境下我最推荐的做法是在本机Hosts文件里绑定一个虚构的内网域名比如ncdev.local而不是直接使用localhost或IP地址访问系统。原因很简单NCCloud的OAuth2.0、SSO单点登录、跨域Cookie共享都强依赖域名信息。你用localhost:8080访问时Cookie的Domain属性会是localhost一旦切换到局域网IP又得重新登录而用一个固定的测试域名每个环境都能复用同一套登录态。Windows下修改C:\Windows\System32\drivers\etc\hostsLinux下修改/etc/hosts加入一行127.0.0.1 ncdev.local然后记得清理浏览器缓存里的DNS解析记录。别小看这一步很多登录成功后跳回登录页的问题十有八九就是域名和Cookie不匹配导致的。2.3 数据库客户端与版本选择NCCloud目前对主流关系型数据库都有对应的适配版本开发环境我建议优先使用官方文档推荐度最高的那一种通常是Oracle或PostgreSQL。如果你只是做普通的功能开发数据库选型和生产一致最重要但如果你涉及SQL性能调试、存储过程编写那就要注意开发库的数据量不要太少否则你做的索引优化根本压不出差异。数据库客户端的准备同样重要。你至少要有一个能执行SQL脚本的工具比如DBeaver、Navicat或者命令行客户端因为NCCloud首次安装时需要执行大量初始化脚本。别用那种只能看表结构、不能执行批量脚本的轻量工具执行到一半报错还得从头来非常痛苦。另外一个实用经验在执行初始化SQL前先手动创建一个专门给NCCloud用的数据库账号最小化授权。这样即使后续有人误操作也不会波及整个数据库实例。3. 数据库与中间件的安装配置细节3.1 数据库实例初始化字符集与排序规则不能拍脑袋数据库装好后第一件事是规划好字符集。NCCloud的多语言数据和单据编号都依赖数据库的字符集支持如果建库时选了不支持的字符集后面导入初始化数据时会出现大量的乱码、字段截断甚至直接报ORA-12899之类的长度错误。我的习惯是统一采用UTF-8具体到PostgreSQL是UTF8编码、en_US.UTF-8或C排序规则Oracle则是AL32UTF8。你可能会说我开发环境不涉及多语言用啥都行但我劝你千万别偷懒。因为一旦后面要在同一套环境里接上别的业务系统或者从生产环境同步数据备份过来字符集不一致会让你悔不当初。3.2 中间件从TongWeb到独立进程的取舍在生产环境中NCCloud往往部署在企业级商用中间件如TongWeb里但在开发机上跑中间件有两个选择使用NCCloud自带的集成式启动脚本也就是官方安装包解压后直接启动的方式内置了运行时环境适合快速启动、不关心部署结构的场景部署到独立中间件适合需要模拟生产真实结构、做类加载隔离调试的场景。开发初期用集成式启动就好能少踩一半的坑。集成式启动脚本内部已经帮你做好了端口、JVM参数、日志路径的默认配置你要做的只是按照安装向导把数据库连接信息填对。等到后面项目进入联调阶段再把应用部署到独立中间件上稳定跑一段时间这个可以自行控制节奏。3.3 Redis和文件服务这些辅助组件什么时候才需要功能相对独立的模块如果不涉及会话共享Redis可以晚点再装。但NCCloud的很多业务组件都依赖Redis做缓存和分布式锁尤其是多节点部署时根本绕不开。我的建议是开发环境把Redis一并装上配置密码然后设置内存上限。Redis的配置文件里有两个参数一定要调maxmemory 1gb maxmemory-policy allkeys-lru为什么非设不可NCCloud的缓存KEY非常多如果用默认的不限制内存时间一长Redis会吃掉你大半个开发机的内存导致系统Swap。allkeys-lru策略会在内存达到上限时自动淘汰最久未使用的KEY保证Redis进程本身不会OOM。一个真实的开发场景里这个配置帮我避免了无数次跑着跑着数据库连接突然全部断掉的问题。3.4 Nginx反向代理与静态资源分离前端的JS、CSS等静态资源打包出来后动辄几十上百MB如果全部由应用服务去加载启动慢且浪费服务器带宽。所以开发环境配一个Nginx反向代理是非常有必要的它可以帮你做三件事将静态资源和动态接口分开转发前端页面访问速度明显提升隐藏后端真实端口前端只需要固定访问一个端口联调时不用频繁改代码解决跨域问题——前端和后端用同一个域名、不同路径访问从根上规避了CORS。写一个开发环境可用的Nginx配置片段示例server { listen 80; server_name ncdev.local; # 前端静态资源 location / { root /data/nccloud/web; index index.html; 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; } # 文件上传下载 location /files/ { alias /data/nccloud/files/; } }注意proxy_pass后面的URL结尾不要加多余的路径否则转发规则很容易乱。写完配置后执行nginx -t验证语法再nginx -s reload让配置生效。4. NCCloud服务端部署与启动4.1 安装包的解压与目录结构说明NCCloud的安装包一般是一个压缩包解压后你会看到类似这样的结构不同小版本会有差异但核心模块是稳定的nccloud/ ├── bin # 启动、停止、维护脚本 ├── modules # 各种业务模块的jar包或war包 ├── conf # 配置文件 ├── logs # 运行日志 ├── temp # 临时文件 ├── deploy/ └── hotwebs # 热部署资源目录这里我最想提醒大家的是两个目录conf和hotwebs。conf里放着各种组件的配置文件包括数据源、缓存、消息队列、第三方接口对接参数。改配置前先备份这是老生常谈但我见过太多同事改完发现回不去了。hotwebs是NCCloud做前端资源热部署的重要目录你改了前端代码后可以直接把构建产物扔到这个目录下不用重启服务就能生效对开发调试来说能节约大量时间。4.2 数据源配置一次填对少求人数据源配置是部署流程里最容易出问题的一步。找到配置文件不同版本文件名可能不太一样一般是database.properties或db.properties里面会让你配置数据库地址、端口、实例名、账号和密码。配置数据源时有几个细节别踩雷数据库地址尽量写固定IP或内网域名不要写成localhost。因为NCCloud服务可能以服务方式启动你的网络环境一旦变化localhost指向的内容可能和预期不同。账号权限要够但别超纲。建议给NCCloud的数据库账号授予增删改查和DDL权限但不要直接给它DBA权限避免后续误删生产数据开发环境相对无所谓但从一开始就养成好习惯。应用连接串和驱动类不要混版本。比如你用的是PostgreSQL 14驱动包就不能拿老版本的去凑否则会出现SSL connection error或者类型转换异常。下面是一个典型的数据源配置片段以PostgreSQL为例db.typepostgresql db.host192.168.1.100 db.port5432 db.namenccloud db.userncuser db.passwordencrypted_password db.maxconnections50 db.minconnections5密码一般支持加密存储首次配置可以先填明文启动成功后再用工具加密替换。4.3 首次启动与初始化向导配置文件准备好了接下来就是启动服务。第一次启动别直接跑到后台去我建议在前台模式下启动这样可以看到完整的启动日志报错也更容易定位。启动完成后浏览器访问http://ncdev.local/正常情况下会进入NCCloud的初始化向导页面。初始化向导会要求你选择数据库类型、输入数据库连接信息、创建系统管理员账号、导入初始数据等。这里说一个很重要的经验初始化过程千万别中途断开。这个步骤会创建几十个系统表写入大量基础数据如果中途失败下次执行前得先把之前建好的库清空重来一次。我就见过同事初始化做到一半电脑断电结果再启动时各种功能报错最后只能把数据库删掉从头来白白浪费了一整个下午。4.4 启动失败的常见报错排查我把开发中最常遇到的启动报错整理成了一张排查表供你对照报错现象可能原因解决思路报错数据库连接超时数据库没启动/网络不通/端口被防火墙拦截先用数据库客户端测试连通性报ClassNotFoundException驱动包缺失或版本不匹配检查lib目录下是否有对应数据库驱动报端口被占用8080或其他端口已被其他服务占用找到占用进程换用闲置端口启动到一半停住不动可能是初始化数据脚本执行时间长观察日志看是否还卡在SQL执行阶段报权限不足应用运行账号对日志、文件目录没有写权限检查所有工作目录的属主和权限页面能打开但接口报401登录态失效/Redis会话未同步检查Redis配置、Cookie域名设置排查启动问题有一个很实用的思路顺着日志一层层往外看。先看NCCloud的应用日志再看中间件日志最后看数据库日志。很多时候应用日志只告诉你连接不上数据库但数据库日志会告诉你具体是认证失败、网络不通还是连接数被占满。定位问题时越靠近底层越容易找到根因。5. 开发联调环境的搭建前端、后端与调试技巧5.1 前端工程构建与启动NCCloud的前端工程一般是一个独立的前端项目使用Vue或React技术栈。拿到前端代码后执行依赖安装和本地启动npm install npm run serve这里我强烈建议用固定的Node.js版本。NCCloud前端的构建工具链对Node版本有要求太新的Node比如18容易在node-sass或sharp这些原生模块上踩坑所以尽量和团队其他成员保持一致。项目根目录的.nvmrc或package.json里一般会有版本提示如果没有直接问项目里谁的环境是顺畅的看他的版本号。开发调试时前端本地服务的端口通常是8081、8082之类的自定义端口。这个时候有两种调试方式跨域代理在前端vue.config.js中配置proxy把/api代理到后端8080端口统一Nginx入口把前端构建产物放到Nginx的静态目录下由Nginx统一转发。我实际工作中更推荐第二种。原因很简单它和你最终上线的形态一致调试时能顺带把Nginx的转发规则、缓存策略一起验证了。用第一方案虽然开发时少一些配置但联调阶段总要迁到Nginx上去早点用反而省事。5.2 后端模块的热部署与远程调试NCCloud的服务端毕竟是庞大的单体应用每次改一行Java代码要重启整个服务是非常劝退的。所以开发环境一定要会用热部署和远程调试。NCCloud提供的hotwebs目录就是专门给前端资源热部署用的你改完前端代码构建产物放置到该目录对应的模块路径下刷新页面就能看到效果。对于后端Java代码则依赖你使用的中间件/启动方式来实现热部署。如果你用IDE比如IDEA直接启动可以开启DevTools或者使用JRebel这类工具。配置远程调试端口则是在启动脚本里加上JVM参数-agentlib:jdwptransportdt_socket,servery,suspendn,address8787地址端口8787是我常用的调试端口。这样的话即使服务是启动在虚拟机或远程服务器上也能从本地IDE打上断点进行调试。这在你排查本地正常、服务器上报错的问题时特别高效。5.3 版本控制与数据库同步的配合开发环境搭建的最后一环是把版本管理这个环节理顺。团队合作时每个人本地都有一套NCCloud环境数据库的初始数据必须同步否则你本地死活复现不了别人的Bug因为数据不一样。我的做法是维护一套统一的初始化数据库备份。每当有同事执行了数据字典变更新建表、加字段就导出一份最新的数据字典脚本放在代码仓库里。新成员加入或者环境重建时直接用这份脚本初始化数据库能节省大量对账的时间。同时NCCloud自身的模块补丁管理也要注意。同一个项目组里大家手里的安装包版本尽量保持一致别出现你用的是1909版本同事却用了2206版本那联调时各种页面差异会让你怀疑人生。6. 高频故障排查经验与性能调优补充6.1 启动慢、内存不足这类慢性病怎么处理NCCloud启动慢是常态不用慌。如果你发现启动时间达到十几分钟甚至更长先检查JVM堆内存设置。默认情况下可能不太合理你可以在启动脚本里调整-Xms2048m -Xmx4096m-Xms和-Xmx配成一样可以避免运行时频繁扩容带来的卡顿。另外一个容易被忽视的地方是临时目录权限。Linux环境下如果/tmp目录的权限不对应用在解压临时文件时会非常慢。执行df -h看看磁盘空间free -h看看内存是不是被其他进程吃光了。我见过有同事的机器上开了一堆Docker容器和Electron应用物理内存只剩2GBNCCloud不卡才有鬼。6.2 数据库连接被打满的排查链路有一次我在开发环境遇到一个诡异的现象上午一切正常下午一到班所有接口都报数据库连接超时。查了半天性能指标最后发现是有个同事在本地跑了一个批量处理的测试脚本把整个开发库的数据锁了一部分连接池被大量长时间事务占着不释放。最后把那个事务杀掉系统立刻恢复。这个案例说明两件事。第一开发环境也要注意锁竞争批量操作尽量在业务低峰期跑第二连接池的maxconnections不要设置得太小50个左右对于小团队足够用但也不建议无限调大因为数据库实例能承受的连接数是有限的。排查连接数问题你可以登录到数据库里查看当前活动连接-- PostgreSQL SELECT count(*), state FROM pg_stat_activity GROUP BY state;如果发现大量连接卡在idle in transaction状态那基本就是应用事务没提交或没回滚。找到对应的PID后把它杀掉或让对应开发同事检查一下代码逻辑。6.3 前端白屏与缓存不回源的问题开发环境下前端白屏大概率不是代码问题而是浏览器缓存了旧版本的JS文件。我习惯的做法是首次联调时打开开发者工具把Network的Cache禁用掉再刷新一遍。等确定代码运行正常后再恢复正常缓存模式。如果你用的是Nginx托管前端资源给CSS/JS加上版本号参数是个好习惯location ~* \.(js|css)$ { expires 7d; add_header Cache-Control public; }但开发环境建议把expires设置为off或者非常短的时间否则每次修改前端代码后刷新页面看到的还是旧内容容易误判成代码没生效。6.4 日志管理平时不起眼出问题救命最后压轴的部分我必须强调日志管理。NCCloud的日志文件散落在不同组件目录里出问题时要同时看几个日志才能拼出完整链路。我的做法是把它统一做一次软链接或直接通过rsync等方式汇总到/data/nccloud/logs目录下面。实际开发中建议重点关注以下日志文件app.log或stdout.log应用主日志业务异常、事务失败都在这里error.log应用错误汇总access.logHTTP访问日志排查请求是否打到服务端db_query.log慢SQL和数据库相关日志部分版本开启后才有。日志级别也别一直开在INFO以上。联调阶段把日志级别调成DEBUG能看到具体的SQL参数和调用链路排查效率翻倍但正常跑环境时记得调回INFO否则一天能写好几个GB的日志磁盘说爆就爆。7. 写在最后搭建开发环境的一点个人体会NCCloud开发环境搭建这件事看起来是按文档执行的体力活但真正做下来你会发现它考验的是对系统组件关系的理解程度。你越是清楚每个组件解决什么问题、数据在每个环节之间怎么流转遇到问题时就越能准确判断该去哪一层找线索。我自己的体会是开发环境是连接业务需求和代码实现的桥梁多花一点时间把它维护好后续的每次功能开发、问题排查都会顺畅很多。如果你刚好卡在某一环节别急着重装系统或删库重来先看日志再看配置再查网络。按这个顺序排查绝大多数问题都能在一个小时内定位到。祝你的环境一次搭通。