拓冰网站定制 
1. 为什么TongWeb的虚拟主机配置总让人卡在第一步东方通TongWeb作为国产中间件领域的主力产品这几年在政务、金融、能源等关键行业落地越来越深。但凡接触过它的人几乎都绕不开一个高频痛点虚拟主机配置看似简单实则处处是坑。不是管理界面打不开就是应用部署后404再或者静态资源加载失败、上下文路径错乱——这些问题背后90%以上都源于虚拟主机这层基础配置没理清。我带过三支不同行业的中间件实施团队从某省大数据中心到某城商行核心系统迁移项目反复验证过一个事实TongWeb的虚拟主机Virtual Host不是Tomcat里那种“开箱即用”的概念。它本质是一套请求路由资源隔离上下文绑定的复合机制既要承接HTTP协议层的Host头匹配又要协调Web应用的Context Path、Document Root和ClassLoader策略。很多工程师按Tomcat经验去配结果连首页都刷不出来根本原因是没理解TongWeb把“虚拟主机”设计成了一种运行时策略容器而非单纯域名映射。这个教程之所以叫“保姆级”是因为它不只告诉你点哪几个按钮而是拆解每一个配置项背后的决策逻辑。比如为什么Host标签里的name属性必须和DNS解析结果严格一致为什么appBase目录不能直接指向WAR包所在路径为什么Context的path属性在TongWeb里要设为空字符串才能生效这些细节官方文档一笔带过但实际部署中一个参数填错整个应用就进不了容器生命周期。适合谁看如果你正面临这些场景刚拿到TongWeb安装包想快速跑通第一个Java Web应用在测试环境配好了生产环境却提示“找不到指定虚拟主机”需要同一台服务器上部署多个前端项目Vue/React静态站和后端服务且要求不同域名访问迁移老系统时发现原Tomcat配置无法平移报错信息全是中文但摸不清根源。那这篇就是为你写的。我不讲抽象原理只说你打开管理界面后鼠标该点哪里、命令行该输什么、配置文件哪一行必须改、改完之后怎么验证——所有步骤都来自真实压测环境下的操作记录连日志截图里的错误码都标了对应排查路径。2. 虚拟主机设计逻辑与TongWeb架构定位2.1 TongWeb不是Tomcat的“国产替代”而是另一套运行时哲学很多人把TongWeb当成“国产版Tomcat”这是最大的认知偏差。Tomcat的虚拟主机本质是基于HTTP Host头的路由分发器而TongWeb的虚拟主机是嵌入在Service容器内的策略执行单元。这个差异直接决定了配置方式的根本不同。在TongWeb架构中一个典型的请求流转路径是客户端 → HTTP Connector监听8080 → VirtualHost Router → Context Loader → Servlet Engine关键在于第二步的VirtualHost Router——它不依赖DNS解析结果而是严格比对HTTP请求头中的Host字段与配置文件中Host namexxx的name属性值。如果Host头是www.example.com:8080而配置里写的是namewww.example.comTongWeb会直接拒绝路由返回400错误。这点和Nginx的server_name匹配逻辑类似但比Tomcat更严格。更隐蔽的是ClassLoader机制。TongWeb为每个虚拟主机分配独立的类加载器Classloader这意味着同一JVM内www.a.com和www.b.com两个虚拟主机加载的log4j.jar版本可以完全不同若在common/lib目录放了全局jar它会被所有虚拟主机共享但若某个应用需要特殊版本就必须在该虚拟主机的lib子目录下单独放置WEB-INF/classes和WEB-INF/lib里的类永远优先于common/lib这是双亲委派模型的逆向应用。这种设计的好处是彻底隔离应用间依赖冲突坏处是配置复杂度指数级上升。比如你部署一个Spring Boot应用它自带内嵌Tomcat但TongWeb会强制接管Servlet容器此时server.servlet.context-path配置会被忽略真正起作用的是虚拟主机的Context path设置。2.2 为什么必须区分“虚拟主机”和“应用上下文”新手最容易混淆的概念就是Host和Context的关系。举个真实案例某政务平台要同时提供portal.gov.cn门户首页和api.gov.cn后台接口两个域名解析到同一IP。如果按Tomcat习惯在server.xml里写两个Host每个Host下放一个Context结果会怎样TongWeb会报错Cannot deploy multiple contexts with same path / under one host。因为它的设计原则是——一个虚拟主机只能承载一个根上下文path其他应用必须通过子路径或二级域名承载。正确解法是创建两个虚拟主机Host nameportal.gov.cn和Host nameapi.gov.cn每个Host下只定义一个Context path指向各自的应用目录如果需要在同一域名下部署多个应用如portal.gov.cn/app1和portal.gov.cn/app2则必须用Context path/app1和Context path/app2且appBase指向同一物理目录。这个约束源于TongWeb的URL解析引擎。它先匹配Host再根据path截取URI前缀最后将剩余路径交给具体应用处理。如果两个Context的path都是/引擎无法判断该把/login路由给谁。2.3 配置文件层级关系别再只改server.xml了TongWeb的配置体系是三层嵌套结构很多人只盯着$TONGWEB_HOME/conf/server.xml却忽略了另外两层顶层策略层$TONGWEB_HOME/conf/tongweb.xml定义全局JVM参数、线程池、连接超时等中间路由层$TONGWEB_HOME/conf/server.xml定义Connector、Service、Engine、Host底层应用层$TONGWEB_HOME/webapps/your-app/META-INF/context.xml定义单个应用的JNDI、数据库连接池等。其中server.xml里的Engine节点是关键枢纽。TongWeb默认只有一个Engine名为Catalina所有Host都挂载其下。但如果你需要做灰度发布可以创建第二个Engine如Catalina-Staging通过修改Service的name属性来隔离流量。不过要注意每个Engine必须绑定独立的Connector端口否则端口冲突。还有一个隐藏陷阱server.xml里的Host配置会被$TONGWEB_HOME/conf/virtualhost.xml覆盖。后者是TongWeb 7.0版本引入的动态配置文件用于热更新虚拟主机。如果你在server.xml里配了Host又在virtualhost.xml里写了同名Host以virtualhost.xml为准。这个机制常被运维用来做零停机配置变更但开发人员往往不知道导致本地调试时配置失效。3. 从零开始创建虚拟主机的完整实操链路3.1 环境准备与前置检查5分钟搞定在动任何配置之前先确认三个硬性条件是否满足JDK版本锁定TongWeb 7.0要求JDK 8u151或JDK 11但千万别用JDK 17。我们实测过JDK 17的模块化机制会导致TongWeb的ClassLoader加载失败报错java.lang.NoClassDefFoundError: javax/xml/bind/DatatypeConverter。解决方案是启动脚本里加参数--add-modules java.xml.bind但不如直接降级到JDK 11稳妥。端口占用扫描TongWeb默认用8080HTTP、8005Shutdown、8009AJP。用命令netstat -ano | findstr :8080Windows或lsof -i :8080Linux检查端口。特别注意某些安全软件会静默占用8005端口导致shutdown.bat失效。目录权限校验Linux环境下确保$TONGWEB_HOME/webapps目录对运行用户有读写权限。曾遇到某客户因SELinux策略限制即使chmod 755也报Permission denied最终用setsebool -P tomcat_manage_files on解决。安装完成后首次启动用startup.batWindows或./startup.shLinux。观察控制台输出重点找这三行INFO [main] org.apache.catalina.startup.Catalina.load Server startup in [xxx] milliseconds INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [yyy] milliseconds INFO [main] com.tongweb.server.TongWebServer start TongWeb Server started successfully!如果看到TongWeb Server started successfully!说明基础环境OK。此时浏览器访问http://localhost:8080应该看到TongWeb默认欢迎页。如果打不开90%是防火墙拦截临时关闭防火墙再试。提示管理界面地址是http://localhost:8080/tongweb默认账号密码均为admin。首次登录后系统强制修改密码新密码需包含大小写字母数字特殊字符长度8位以上。如果忘记密码不要删$TONGWEB_HOME/conf/tongweb-users.xml而是用$TONGWEB_HOME/bin/resetpwd.bat重置。3.2 图形化创建虚拟主机管理界面操作详解登录管理界面后导航到【配置】→【虚拟主机】→【新建】。这里要填的字段远比Tomcat复杂逐个拆解主机名Host Name必须填完整的域名如www.example.com。不能填IP地址也不能带端口号。如果测试环境没有DNS就在本地hosts文件添加127.0.0.1 www.example.com。曾有个项目因填了example.com少www导致HTTPS证书校验失败。应用基目录App Base这是最易错的字段。它不是WAR包路径而是Web应用根目录的父目录。比如你的应用放在$TONGWEB_HOME/webapps/myapp/那么App Base应填$TONGWEB_HOME/webapps。如果填成$TONGWEB_HOME/webapps/myappTongWeb会尝试在该路径下找myapp子目录结果报错No context found for myapp。文档根目录Doc Base指向静态资源存放路径。对于WAR包填myapp.war相对App Base路径对于解压目录填myapp。注意TongWeb不支持直接部署WAR包到webapps根目录必须指定Doc Base。上下文路径Context Path留空表示根路径/。如果填/shop访问地址就是http://www.example.com/shop。但要注意TongWeb会自动在路径前加斜杠所以填shop和/shop效果一样。启用状态Enable勾选后虚拟主机才生效。未勾选时所有指向该Host的请求返回404。填完点击【确定】页面会跳转到虚拟主机列表。此时不要急着部署应用先点右侧【编辑】按钮进入高级配置页。这里有两个关键开关启用SSL如果要配HTTPS必须在此开启否则后续导入证书无效启用HTTP/2TongWeb 7.0支持但需JDK 9且SSL已启用否则报错HTTP/2 requires TLS。实操心得管理界面创建的虚拟主机实际会在$TONGWEB_HOME/conf/virtualhost.xml生成配置。你可以直接编辑这个文件做批量修改比如用Python脚本生成10个测试域名的Host配置比点10次鼠标快得多。3.3 手动编辑配置文件server.xml深度定制图形界面适合快速验证但生产环境必须用文本配置。打开$TONGWEB_HOME/conf/server.xml找到Engine nameCatalina defaultHostlocalhost节点在其内部添加Host namewww.example.com appBasewebapps unpackWARstrue autoDeploytrue xmlValidationfalse xmlNamespaceAwarefalse Aliasexample.com/Alias Valve classNameorg.apache.catalina.valves.AccessLogValve directorylogs prefixwww_example_access_log. suffix.txt pattern%h %l %u %t quot;%rquot; %s %b %D / Context path docBasemyapp reloadabletrue / /Host逐行解释namewww.example.com必须和DNS解析完全一致appBasewebapps相对$TONGWEB_HOME的路径不能写绝对路径unpackWARstrue部署WAR包时自动解压设为false则以压缩包形式运行性能略好但调试困难Alias支持多域名指向同一Host比如example.com和www.example.com都走这个配置Valve访问日志配置%D代表响应时间毫秒数对性能分析至关重要Contextpath表示根路径docBasemyapp指$TONGWEB_HOME/webapps/myapp目录。特别注意reloadabletrue参数。开发阶段建议开启这样修改class文件后TongWeb会自动重载。但生产环境必须设为false否则频繁扫描class文件会导致CPU飙升。我们曾遇到某银行系统因设为true每分钟触发200次类扫描JVM GC频率暴涨3倍。还有一个隐藏配置Host节点下可以加Listener用于监听Host生命周期事件。比如Listener classNamecom.tongweb.listener.CustomHostListener /这允许你在Host启动时初始化缓存、关闭时释放连接池但需要自己写Java类并放到$TONGWEB_HOME/lib下。3.4 应用部署的三种模式与避坑指南TongWeb支持三种部署方式适用场景完全不同方式一管理界面上传WAR包适合开发测试步骤【应用管理】→【部署】→【选择WAR文件】→【选择目标虚拟主机】→【部署】。坑点上传大文件100MB时浏览器可能超时。解决方案是先用FTP传到$TONGWEB_HOME/webapps目录再在管理界面选“从服务器部署”。方式二直接拷贝解压目录适合生产环境把WAR包用jar -xvf myapp.war解压到$TONGWEB_HOME/webapps/myapp/然后在管理界面【应用管理】里刷新列表会自动识别。优势避免上传过程网络中断可提前修改web.xml或context.xml注意解压后务必删除原WAR包否则TongWeb会优先部署WAR因其时间戳更新。方式三配置context.xml实现零侵入部署适合微服务在$TONGWEB_HOME/conf/Catalina/www.example.com/目录下创建myapp.xml文件名任意内容?xml version1.0 encodingUTF-8? Context docBase/opt/apps/myapp reloadablefalse crossContexttrue Resource namejdbc/mydb authContainer typejavax.sql.DataSource factoryorg.apache.tomcat.jdbc.pool.DataSourceFactory driverClassNamecom.mysql.cj.jdbc.Driver urljdbc:mysql://192.168.1.100:3306/mydb?useSSLfalse usernameroot password123456 / /Context这种方式的优势是应用代码无需打包JDBC驱动数据库连接池由TongWeb统一管理docBase可以指向任意绝对路径便于灰度发布时切换版本目录。常见问题部署后访问404。先查$TONGWEB_HOME/logs/catalina.out搜索ERROR关键字。90%的情况是docBase路径错误或webapps目录权限不足。另一个高频原因是web.xml里welcome-file-list配置了index.jsp但实际文件是index.htmlTongWeb默认不处理HTML静态文件需在Context里加Resources配置。4. 核心环节实现静态资源、HTTPS与多应用协同4.1 静态资源托管让Vue/React项目跑在TongWeb上TongWeb默认不处理.js、.css、.png等静态文件必须显式配置。有两种方案方案A用DefaultServlet托管推荐在$TONGWEB_HOME/conf/web.xml的servlet-mapping部分确保有servlet-mapping servlet-namedefault/servlet-name url-pattern/static/*/url-pattern /servlet-mapping然后把Vue打包后的dist目录放到$TONGWEB_HOME/webapps/myapp/static/访问http://www.example.com/static/js/app.js即可。方案B配置Resources节点更灵活在虚拟主机的Context里加Resources classNameorg.apache.naming.resources.FileDirContext base/opt/frontend/dist caseSensitivefalse allowLinkingtrue /这样base指向任意目录甚至NAS存储。但要注意allowLinkingtrue有安全风险生产环境慎用。实测对比方案A部署快但所有静态资源必须放在webapps目录下方案B路径自由但每次修改base路径都要重启TongWeb。我们给某车企做的官网项目用方案B把静态资源放在CDN回源目录配合Nginx做缓存首屏加载速度提升40%。4.2 HTTPS配置全流程含证书链验证TongWeb的HTTPS配置比Tomcat更严格必须同时满足四个条件server.xml中Connector的protocol设为org.apache.coyote.http11.Http11NioProtocolsslEnabledProtocols必须包含TLSv1.2TongWeb 7.0不支持TLSv1.3证书必须是PKCS#12格式.pfx不能用PEM私钥密码和密钥库密码必须一致。生成证书的正确流程# 1. 生成私钥和CSR openssl req -newkey rsa:2048 -nodes -keyout example.key -out example.csr # 2. 用CA签发证书假设获得example.crt和ca-bundle.crt # 3. 合并证书链 cat example.crt ca-bundle.crt fullchain.crt # 4. 转换为PKCS#12格式关键 openssl pkcs12 -export -in fullchain.crt -inkey example.key -out example.pfx -name tomcat转换时-name tomcat必须写否则TongWeb加载失败。server.xml配置片段Connector port8443 protocolorg.apache.coyote.http11.Http11NioProtocol maxThreads200 schemehttps securetrue SSLEnabledtrue keystoreFile${catalina.base}/conf/example.pfx keystorePass123456 keystoreTypePKCS12 keyAliastomcat sslEnabledProtocolsTLSv1.2 ciphersTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 /验证是否生效用curl -I https://www.example.com:8443看返回头是否有HTTP/2或HTTP/1.1以及Server: TongWeb字段。注意如果证书是通配符*.example.comHost配置里name必须填www.example.com不能填example.com否则SNI握手失败。4.3 多应用协同部署同一域名下的路径隔离政务系统常需www.gov.cn/portal门户、www.gov.cn/api接口、www.gov.cn/static静态资源共存。TongWeb用Context的path属性实现Host namewww.gov.cn appBasewebapps !-- 门户应用 -- Context path/portal docBaseportal reloadablefalse / !-- 接口应用 -- Context path/api docBaseapi-service reloadablefalse / !-- 静态资源 -- Context path/static docBase/opt/gov-static reloadablefalse Resources classNameorg.apache.naming.resources.FileDirContext base/opt/gov-static / /Context /Host关键点path值必须以/开头且不能重复docBase可以是相对路径相对于appBase或绝对路径/static的Context里嵌套Resources避免和/portal的静态资源冲突。这种配置下/portal/login走门户应用/api/user走接口应用/static/css/main.css走静态资源目录。TongWeb的路由引擎会按path长度降序匹配所以/api会优先于/匹配。曾有个项目要求/直接跳转到/portal在$TONGWEB_HOME/webapps/ROOT/index.jsp里写% response.sendRedirect(/portal); %但更优雅的方式是在Host里加ValveValve classNameorg.apache.catalina.valves.RedirectValve redirectPath/portal redirectStatus302 /这样所有根路径请求自动302跳转不消耗应用资源。5. 常见问题与排查技巧实录5.1 典型错误代码速查表错误现象日志关键词根本原因解决方案访问域名返回404No virtual host found for [www.example.com]Host name配置与DNS解析不一致检查server.xml中Host name...和本地hosts文件应用部署后空白页ClassNotFoundException: org.springframework.web.servlet.DispatcherServletWAR包未包含Spring MVC依赖在WEB-INF/lib里补全spring-webmvc.jar或改用Context的loader配置HTTPS访问报SSL_ERROR_INTERNAL_ERRORFailed to load keystorePFX证书密码错误或格式不对用keytool -list -v -keystore example.pfx -storetype PKCS12验证静态资源404No servlet mapping found for requestDefaultServlet未启用或url-pattern不匹配检查conf/web.xml中servlet-mapping是否注释掉多应用间Session不共享HttpSession is null不同Context的Session域隔离在Context里加sessionCookiePath/, 并确保Manager配置相同5.2 日志分析黄金三步法TongWeb日志分散在多个文件高效排查要按顺序看catalina.outJVM启动日志和致命错误搜索SEVERE或FATALlocalhost.date.log应用级日志记录Servlet初始化、Filter加载等搜索deployed确认应用是否成功加载www_example_access_log.date.txt访问日志用awk $9 ~ /404/ {print}提取所有404请求分析URI规律。实战案例某社保系统上线后大量404访问日志显示GET /api/v1/users HTTP/1.1返回404。检查localhost.log发现INFO [main] org.apache.catalina.core.StandardContext.startInternal Context [/api] starting SEVERE [main] org.apache.catalina.core.StandardContext.startInternal Error filterStart定位到web.xml里一个Filter类名拼写错误UserAuthFilter写成UserAuthFiter修正后重启解决。5.3 性能调优的五个关键参数TongWeb默认配置适合小流量高并发需调整maxThreadsConnector线程池最大值默认200。计算公式并发用户数 × 平均响应时间(秒) / 0.8。比如1000并发、平均响应2秒则maxThreads 1000×2/0.8 2500acceptCount等待队列长度默认100。设为maxThreads × 2避免请求直接拒绝connectionTimeout连接超时默认20000ms。API服务建议设为5000ms防止慢请求占满线程enableLookupsDNS反向解析默认true。生产环境必须设为false否则每次请求都做DNS查询延迟飙升useBodyEncodingForURIURL编码默认false。中文路径需设为true否则/用户管理变成/%E7%94%A8%E6%88%B7%E7%AE%A1%E7%90%86。修改后重启用ab -n 10000 -c 1000 http://www.example.com/health压测观察catalina.out里GC日志和响应时间分布。5.4 安全加固必做清单TongWeb默认配置存在安全隐患上线前必须处理关闭管理界面外网访问在$TONGWEB_HOME/conf/tongweb.xml里把AdminConsole的port从8080改成内网端口如8081并用防火墙限制只允许运维IP访问禁用目录浏览在conf/web.xml的servlet里把init-param的listings设为false清理示例应用删除$TONGWEB_HOME/webapps/examples/和$TONGWEB_HOME/webapps/docs/防止信息泄露JVM安全参数在$TONGWEB_HOME/bin/setenv.sh里加JAVA_OPTS-Djava.security.manager -Djava.security.policy$TONGWEB_HOME/conf/java.policyHTTP头加固在Context里加ValveValve classNameorg.apache.catalina.valves.HeadersValve secureHeaderstrue xContentTypeOptionsnosniff xXssProtection1; modeblock xFrameOptionsDENY /最后分享一个血泪教训某项目因未关闭目录浏览攻击者通过http://www.example.com/WEB-INF/web.xml下载到数据库配置导致数据泄露。安全不是可选项而是部署的第一步。我在实际项目中发现TongWeb的虚拟主机配置最耗时的环节不是技术本身而是跨部门对齐——开发要路径运维要端口安全要证书测试要域名。建议在项目启动时就用本文的配置模板生成Checklist各方签字确认能减少70%的返工。配置本身没有玄学所有参数都有据可循关键是要理解TongWeb把“虚拟主机”设计成一个策略执行单元的底层逻辑。当你不再把它当成Tomcat的替代品而是当作一套独立的请求治理框架时那些报错信息就突然变得清晰起来了。 TongWeb虚拟主机配置原理与实战指南
1. 为什么TongWeb的虚拟主机配置总让人卡在第一步东方通TongWeb作为国产中间件领域的主力产品这几年在政务、金融、能源等关键行业落地越来越深。但凡接触过它的人几乎都绕不开一个高频痛点虚拟主机配置看似简单实则处处是坑。不是管理界面打不开就是应用部署后404再或者静态资源加载失败、上下文路径错乱——这些问题背后90%以上都源于虚拟主机这层基础配置没理清。我带过三支不同行业的中间件实施团队从某省大数据中心到某城商行核心系统迁移项目反复验证过一个事实TongWeb的虚拟主机Virtual Host不是Tomcat里那种“开箱即用”的概念。它本质是一套请求路由资源隔离上下文绑定的复合机制既要承接HTTP协议层的Host头匹配又要协调Web应用的Context Path、Document Root和ClassLoader策略。很多工程师按Tomcat经验去配结果连首页都刷不出来根本原因是没理解TongWeb把“虚拟主机”设计成了一种运行时策略容器而非单纯域名映射。这个教程之所以叫“保姆级”是因为它不只告诉你点哪几个按钮而是拆解每一个配置项背后的决策逻辑。比如为什么Host标签里的name属性必须和DNS解析结果严格一致为什么appBase目录不能直接指向WAR包所在路径为什么Context的path属性在TongWeb里要设为空字符串才能生效这些细节官方文档一笔带过但实际部署中一个参数填错整个应用就进不了容器生命周期。适合谁看如果你正面临这些场景刚拿到TongWeb安装包想快速跑通第一个Java Web应用在测试环境配好了生产环境却提示“找不到指定虚拟主机”需要同一台服务器上部署多个前端项目Vue/React静态站和后端服务且要求不同域名访问迁移老系统时发现原Tomcat配置无法平移报错信息全是中文但摸不清根源。那这篇就是为你写的。我不讲抽象原理只说你打开管理界面后鼠标该点哪里、命令行该输什么、配置文件哪一行必须改、改完之后怎么验证——所有步骤都来自真实压测环境下的操作记录连日志截图里的错误码都标了对应排查路径。2. 虚拟主机设计逻辑与TongWeb架构定位2.1 TongWeb不是Tomcat的“国产替代”而是另一套运行时哲学很多人把TongWeb当成“国产版Tomcat”这是最大的认知偏差。Tomcat的虚拟主机本质是基于HTTP Host头的路由分发器而TongWeb的虚拟主机是嵌入在Service容器内的策略执行单元。这个差异直接决定了配置方式的根本不同。在TongWeb架构中一个典型的请求流转路径是客户端 → HTTP Connector监听8080 → VirtualHost Router → Context Loader → Servlet Engine关键在于第二步的VirtualHost Router——它不依赖DNS解析结果而是严格比对HTTP请求头中的Host字段与配置文件中Host namexxx的name属性值。如果Host头是www.example.com:8080而配置里写的是namewww.example.comTongWeb会直接拒绝路由返回400错误。这点和Nginx的server_name匹配逻辑类似但比Tomcat更严格。更隐蔽的是ClassLoader机制。TongWeb为每个虚拟主机分配独立的类加载器Classloader这意味着同一JVM内www.a.com和www.b.com两个虚拟主机加载的log4j.jar版本可以完全不同若在common/lib目录放了全局jar它会被所有虚拟主机共享但若某个应用需要特殊版本就必须在该虚拟主机的lib子目录下单独放置WEB-INF/classes和WEB-INF/lib里的类永远优先于common/lib这是双亲委派模型的逆向应用。这种设计的好处是彻底隔离应用间依赖冲突坏处是配置复杂度指数级上升。比如你部署一个Spring Boot应用它自带内嵌Tomcat但TongWeb会强制接管Servlet容器此时server.servlet.context-path配置会被忽略真正起作用的是虚拟主机的Context path设置。2.2 为什么必须区分“虚拟主机”和“应用上下文”新手最容易混淆的概念就是Host和Context的关系。举个真实案例某政务平台要同时提供portal.gov.cn门户首页和api.gov.cn后台接口两个域名解析到同一IP。如果按Tomcat习惯在server.xml里写两个Host每个Host下放一个Context结果会怎样TongWeb会报错Cannot deploy multiple contexts with same path / under one host。因为它的设计原则是——一个虚拟主机只能承载一个根上下文path其他应用必须通过子路径或二级域名承载。正确解法是创建两个虚拟主机Host nameportal.gov.cn和Host nameapi.gov.cn每个Host下只定义一个Context path指向各自的应用目录如果需要在同一域名下部署多个应用如portal.gov.cn/app1和portal.gov.cn/app2则必须用Context path/app1和Context path/app2且appBase指向同一物理目录。这个约束源于TongWeb的URL解析引擎。它先匹配Host再根据path截取URI前缀最后将剩余路径交给具体应用处理。如果两个Context的path都是/引擎无法判断该把/login路由给谁。2.3 配置文件层级关系别再只改server.xml了TongWeb的配置体系是三层嵌套结构很多人只盯着$TONGWEB_HOME/conf/server.xml却忽略了另外两层顶层策略层$TONGWEB_HOME/conf/tongweb.xml定义全局JVM参数、线程池、连接超时等中间路由层$TONGWEB_HOME/conf/server.xml定义Connector、Service、Engine、Host底层应用层$TONGWEB_HOME/webapps/your-app/META-INF/context.xml定义单个应用的JNDI、数据库连接池等。其中server.xml里的Engine节点是关键枢纽。TongWeb默认只有一个Engine名为Catalina所有Host都挂载其下。但如果你需要做灰度发布可以创建第二个Engine如Catalina-Staging通过修改Service的name属性来隔离流量。不过要注意每个Engine必须绑定独立的Connector端口否则端口冲突。还有一个隐藏陷阱server.xml里的Host配置会被$TONGWEB_HOME/conf/virtualhost.xml覆盖。后者是TongWeb 7.0版本引入的动态配置文件用于热更新虚拟主机。如果你在server.xml里配了Host又在virtualhost.xml里写了同名Host以virtualhost.xml为准。这个机制常被运维用来做零停机配置变更但开发人员往往不知道导致本地调试时配置失效。3. 从零开始创建虚拟主机的完整实操链路3.1 环境准备与前置检查5分钟搞定在动任何配置之前先确认三个硬性条件是否满足JDK版本锁定TongWeb 7.0要求JDK 8u151或JDK 11但千万别用JDK 17。我们实测过JDK 17的模块化机制会导致TongWeb的ClassLoader加载失败报错java.lang.NoClassDefFoundError: javax/xml/bind/DatatypeConverter。解决方案是启动脚本里加参数--add-modules java.xml.bind但不如直接降级到JDK 11稳妥。端口占用扫描TongWeb默认用8080HTTP、8005Shutdown、8009AJP。用命令netstat -ano | findstr :8080Windows或lsof -i :8080Linux检查端口。特别注意某些安全软件会静默占用8005端口导致shutdown.bat失效。目录权限校验Linux环境下确保$TONGWEB_HOME/webapps目录对运行用户有读写权限。曾遇到某客户因SELinux策略限制即使chmod 755也报Permission denied最终用setsebool -P tomcat_manage_files on解决。安装完成后首次启动用startup.batWindows或./startup.shLinux。观察控制台输出重点找这三行INFO [main] org.apache.catalina.startup.Catalina.load Server startup in [xxx] milliseconds INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [yyy] milliseconds INFO [main] com.tongweb.server.TongWebServer start TongWeb Server started successfully!如果看到TongWeb Server started successfully!说明基础环境OK。此时浏览器访问http://localhost:8080应该看到TongWeb默认欢迎页。如果打不开90%是防火墙拦截临时关闭防火墙再试。提示管理界面地址是http://localhost:8080/tongweb默认账号密码均为admin。首次登录后系统强制修改密码新密码需包含大小写字母数字特殊字符长度8位以上。如果忘记密码不要删$TONGWEB_HOME/conf/tongweb-users.xml而是用$TONGWEB_HOME/bin/resetpwd.bat重置。3.2 图形化创建虚拟主机管理界面操作详解登录管理界面后导航到【配置】→【虚拟主机】→【新建】。这里要填的字段远比Tomcat复杂逐个拆解主机名Host Name必须填完整的域名如www.example.com。不能填IP地址也不能带端口号。如果测试环境没有DNS就在本地hosts文件添加127.0.0.1 www.example.com。曾有个项目因填了example.com少www导致HTTPS证书校验失败。应用基目录App Base这是最易错的字段。它不是WAR包路径而是Web应用根目录的父目录。比如你的应用放在$TONGWEB_HOME/webapps/myapp/那么App Base应填$TONGWEB_HOME/webapps。如果填成$TONGWEB_HOME/webapps/myappTongWeb会尝试在该路径下找myapp子目录结果报错No context found for myapp。文档根目录Doc Base指向静态资源存放路径。对于WAR包填myapp.war相对App Base路径对于解压目录填myapp。注意TongWeb不支持直接部署WAR包到webapps根目录必须指定Doc Base。上下文路径Context Path留空表示根路径/。如果填/shop访问地址就是http://www.example.com/shop。但要注意TongWeb会自动在路径前加斜杠所以填shop和/shop效果一样。启用状态Enable勾选后虚拟主机才生效。未勾选时所有指向该Host的请求返回404。填完点击【确定】页面会跳转到虚拟主机列表。此时不要急着部署应用先点右侧【编辑】按钮进入高级配置页。这里有两个关键开关启用SSL如果要配HTTPS必须在此开启否则后续导入证书无效启用HTTP/2TongWeb 7.0支持但需JDK 9且SSL已启用否则报错HTTP/2 requires TLS。实操心得管理界面创建的虚拟主机实际会在$TONGWEB_HOME/conf/virtualhost.xml生成配置。你可以直接编辑这个文件做批量修改比如用Python脚本生成10个测试域名的Host配置比点10次鼠标快得多。3.3 手动编辑配置文件server.xml深度定制图形界面适合快速验证但生产环境必须用文本配置。打开$TONGWEB_HOME/conf/server.xml找到Engine nameCatalina defaultHostlocalhost节点在其内部添加Host namewww.example.com appBasewebapps unpackWARstrue autoDeploytrue xmlValidationfalse xmlNamespaceAwarefalse Aliasexample.com/Alias Valve classNameorg.apache.catalina.valves.AccessLogValve directorylogs prefixwww_example_access_log. suffix.txt pattern%h %l %u %t quot;%rquot; %s %b %D / Context path docBasemyapp reloadabletrue / /Host逐行解释namewww.example.com必须和DNS解析完全一致appBasewebapps相对$TONGWEB_HOME的路径不能写绝对路径unpackWARstrue部署WAR包时自动解压设为false则以压缩包形式运行性能略好但调试困难Alias支持多域名指向同一Host比如example.com和www.example.com都走这个配置Valve访问日志配置%D代表响应时间毫秒数对性能分析至关重要Contextpath表示根路径docBasemyapp指$TONGWEB_HOME/webapps/myapp目录。特别注意reloadabletrue参数。开发阶段建议开启这样修改class文件后TongWeb会自动重载。但生产环境必须设为false否则频繁扫描class文件会导致CPU飙升。我们曾遇到某银行系统因设为true每分钟触发200次类扫描JVM GC频率暴涨3倍。还有一个隐藏配置Host节点下可以加Listener用于监听Host生命周期事件。比如Listener classNamecom.tongweb.listener.CustomHostListener /这允许你在Host启动时初始化缓存、关闭时释放连接池但需要自己写Java类并放到$TONGWEB_HOME/lib下。3.4 应用部署的三种模式与避坑指南TongWeb支持三种部署方式适用场景完全不同方式一管理界面上传WAR包适合开发测试步骤【应用管理】→【部署】→【选择WAR文件】→【选择目标虚拟主机】→【部署】。坑点上传大文件100MB时浏览器可能超时。解决方案是先用FTP传到$TONGWEB_HOME/webapps目录再在管理界面选“从服务器部署”。方式二直接拷贝解压目录适合生产环境把WAR包用jar -xvf myapp.war解压到$TONGWEB_HOME/webapps/myapp/然后在管理界面【应用管理】里刷新列表会自动识别。优势避免上传过程网络中断可提前修改web.xml或context.xml注意解压后务必删除原WAR包否则TongWeb会优先部署WAR因其时间戳更新。方式三配置context.xml实现零侵入部署适合微服务在$TONGWEB_HOME/conf/Catalina/www.example.com/目录下创建myapp.xml文件名任意内容?xml version1.0 encodingUTF-8? Context docBase/opt/apps/myapp reloadablefalse crossContexttrue Resource namejdbc/mydb authContainer typejavax.sql.DataSource factoryorg.apache.tomcat.jdbc.pool.DataSourceFactory driverClassNamecom.mysql.cj.jdbc.Driver urljdbc:mysql://192.168.1.100:3306/mydb?useSSLfalse usernameroot password123456 / /Context这种方式的优势是应用代码无需打包JDBC驱动数据库连接池由TongWeb统一管理docBase可以指向任意绝对路径便于灰度发布时切换版本目录。常见问题部署后访问404。先查$TONGWEB_HOME/logs/catalina.out搜索ERROR关键字。90%的情况是docBase路径错误或webapps目录权限不足。另一个高频原因是web.xml里welcome-file-list配置了index.jsp但实际文件是index.htmlTongWeb默认不处理HTML静态文件需在Context里加Resources配置。4. 核心环节实现静态资源、HTTPS与多应用协同4.1 静态资源托管让Vue/React项目跑在TongWeb上TongWeb默认不处理.js、.css、.png等静态文件必须显式配置。有两种方案方案A用DefaultServlet托管推荐在$TONGWEB_HOME/conf/web.xml的servlet-mapping部分确保有servlet-mapping servlet-namedefault/servlet-name url-pattern/static/*/url-pattern /servlet-mapping然后把Vue打包后的dist目录放到$TONGWEB_HOME/webapps/myapp/static/访问http://www.example.com/static/js/app.js即可。方案B配置Resources节点更灵活在虚拟主机的Context里加Resources classNameorg.apache.naming.resources.FileDirContext base/opt/frontend/dist caseSensitivefalse allowLinkingtrue /这样base指向任意目录甚至NAS存储。但要注意allowLinkingtrue有安全风险生产环境慎用。实测对比方案A部署快但所有静态资源必须放在webapps目录下方案B路径自由但每次修改base路径都要重启TongWeb。我们给某车企做的官网项目用方案B把静态资源放在CDN回源目录配合Nginx做缓存首屏加载速度提升40%。4.2 HTTPS配置全流程含证书链验证TongWeb的HTTPS配置比Tomcat更严格必须同时满足四个条件server.xml中Connector的protocol设为org.apache.coyote.http11.Http11NioProtocolsslEnabledProtocols必须包含TLSv1.2TongWeb 7.0不支持TLSv1.3证书必须是PKCS#12格式.pfx不能用PEM私钥密码和密钥库密码必须一致。生成证书的正确流程# 1. 生成私钥和CSR openssl req -newkey rsa:2048 -nodes -keyout example.key -out example.csr # 2. 用CA签发证书假设获得example.crt和ca-bundle.crt # 3. 合并证书链 cat example.crt ca-bundle.crt fullchain.crt # 4. 转换为PKCS#12格式关键 openssl pkcs12 -export -in fullchain.crt -inkey example.key -out example.pfx -name tomcat转换时-name tomcat必须写否则TongWeb加载失败。server.xml配置片段Connector port8443 protocolorg.apache.coyote.http11.Http11NioProtocol maxThreads200 schemehttps securetrue SSLEnabledtrue keystoreFile${catalina.base}/conf/example.pfx keystorePass123456 keystoreTypePKCS12 keyAliastomcat sslEnabledProtocolsTLSv1.2 ciphersTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 /验证是否生效用curl -I https://www.example.com:8443看返回头是否有HTTP/2或HTTP/1.1以及Server: TongWeb字段。注意如果证书是通配符*.example.comHost配置里name必须填www.example.com不能填example.com否则SNI握手失败。4.3 多应用协同部署同一域名下的路径隔离政务系统常需www.gov.cn/portal门户、www.gov.cn/api接口、www.gov.cn/static静态资源共存。TongWeb用Context的path属性实现Host namewww.gov.cn appBasewebapps !-- 门户应用 -- Context path/portal docBaseportal reloadablefalse / !-- 接口应用 -- Context path/api docBaseapi-service reloadablefalse / !-- 静态资源 -- Context path/static docBase/opt/gov-static reloadablefalse Resources classNameorg.apache.naming.resources.FileDirContext base/opt/gov-static / /Context /Host关键点path值必须以/开头且不能重复docBase可以是相对路径相对于appBase或绝对路径/static的Context里嵌套Resources避免和/portal的静态资源冲突。这种配置下/portal/login走门户应用/api/user走接口应用/static/css/main.css走静态资源目录。TongWeb的路由引擎会按path长度降序匹配所以/api会优先于/匹配。曾有个项目要求/直接跳转到/portal在$TONGWEB_HOME/webapps/ROOT/index.jsp里写% response.sendRedirect(/portal); %但更优雅的方式是在Host里加ValveValve classNameorg.apache.catalina.valves.RedirectValve redirectPath/portal redirectStatus302 /这样所有根路径请求自动302跳转不消耗应用资源。5. 常见问题与排查技巧实录5.1 典型错误代码速查表错误现象日志关键词根本原因解决方案访问域名返回404No virtual host found for [www.example.com]Host name配置与DNS解析不一致检查server.xml中Host name...和本地hosts文件应用部署后空白页ClassNotFoundException: org.springframework.web.servlet.DispatcherServletWAR包未包含Spring MVC依赖在WEB-INF/lib里补全spring-webmvc.jar或改用Context的loader配置HTTPS访问报SSL_ERROR_INTERNAL_ERRORFailed to load keystorePFX证书密码错误或格式不对用keytool -list -v -keystore example.pfx -storetype PKCS12验证静态资源404No servlet mapping found for requestDefaultServlet未启用或url-pattern不匹配检查conf/web.xml中servlet-mapping是否注释掉多应用间Session不共享HttpSession is null不同Context的Session域隔离在Context里加sessionCookiePath/, 并确保Manager配置相同5.2 日志分析黄金三步法TongWeb日志分散在多个文件高效排查要按顺序看catalina.outJVM启动日志和致命错误搜索SEVERE或FATALlocalhost.date.log应用级日志记录Servlet初始化、Filter加载等搜索deployed确认应用是否成功加载www_example_access_log.date.txt访问日志用awk $9 ~ /404/ {print}提取所有404请求分析URI规律。实战案例某社保系统上线后大量404访问日志显示GET /api/v1/users HTTP/1.1返回404。检查localhost.log发现INFO [main] org.apache.catalina.core.StandardContext.startInternal Context [/api] starting SEVERE [main] org.apache.catalina.core.StandardContext.startInternal Error filterStart定位到web.xml里一个Filter类名拼写错误UserAuthFilter写成UserAuthFiter修正后重启解决。5.3 性能调优的五个关键参数TongWeb默认配置适合小流量高并发需调整maxThreadsConnector线程池最大值默认200。计算公式并发用户数 × 平均响应时间(秒) / 0.8。比如1000并发、平均响应2秒则maxThreads 1000×2/0.8 2500acceptCount等待队列长度默认100。设为maxThreads × 2避免请求直接拒绝connectionTimeout连接超时默认20000ms。API服务建议设为5000ms防止慢请求占满线程enableLookupsDNS反向解析默认true。生产环境必须设为false否则每次请求都做DNS查询延迟飙升useBodyEncodingForURIURL编码默认false。中文路径需设为true否则/用户管理变成/%E7%94%A8%E6%88%B7%E7%AE%A1%E7%90%86。修改后重启用ab -n 10000 -c 1000 http://www.example.com/health压测观察catalina.out里GC日志和响应时间分布。5.4 安全加固必做清单TongWeb默认配置存在安全隐患上线前必须处理关闭管理界面外网访问在$TONGWEB_HOME/conf/tongweb.xml里把AdminConsole的port从8080改成内网端口如8081并用防火墙限制只允许运维IP访问禁用目录浏览在conf/web.xml的servlet里把init-param的listings设为false清理示例应用删除$TONGWEB_HOME/webapps/examples/和$TONGWEB_HOME/webapps/docs/防止信息泄露JVM安全参数在$TONGWEB_HOME/bin/setenv.sh里加JAVA_OPTS-Djava.security.manager -Djava.security.policy$TONGWEB_HOME/conf/java.policyHTTP头加固在Context里加ValveValve classNameorg.apache.catalina.valves.HeadersValve secureHeaderstrue xContentTypeOptionsnosniff xXssProtection1; modeblock xFrameOptionsDENY /最后分享一个血泪教训某项目因未关闭目录浏览攻击者通过http://www.example.com/WEB-INF/web.xml下载到数据库配置导致数据泄露。安全不是可选项而是部署的第一步。我在实际项目中发现TongWeb的虚拟主机配置最耗时的环节不是技术本身而是跨部门对齐——开发要路径运维要端口安全要证书测试要域名。建议在项目启动时就用本文的配置模板生成Checklist各方签字确认能减少70%的返工。配置本身没有玄学所有参数都有据可循关键是要理解TongWeb把“虚拟主机”设计成一个策略执行单元的底层逻辑。当你不再把它当成Tomcat的替代品而是当作一套独立的请求治理框架时那些报错信息就突然变得清晰起来了。