1. 项目概述这不是一个普通UI安装而是一套面向开发者的“自托管智能体工作台”落地实践Hermes Web UI这个名字最近在开发者圈子里频繁出现但很多人点开GitHub仓库后第一反应是“这到底是个啥文档里写的Agent、Gateway、WebUI三件套怎么装装完能干啥”——别急我花整整两周时间从零开始把Hermes Web UI在本地Ubuntu 24.04和Windows 11双环境跑通、调稳、汉化、压测还顺手搭了配套的MySQL存储后端和Nginx反向代理。这不是教你怎么敲几行命令复制粘贴而是还原一个真实项目落地时你必然要面对的全部环节依赖冲突怎么解、端口被占怎么办、中文界面为什么只显示一半、为什么登录后看不到Agent列表、日志里反复报Failed to connect to gateway却找不到源头……这些细节官方README不会写Stack Overflow搜不到但它们才是决定你能不能真正在团队里用起来的关键。核心关键词“Hermes Web UI”背后实际指向的是一个轻量级、可离线部署的AI智能体Agent协同管理平台。它不依赖OpenAI或Claude等外部API密钥而是通过本地运行的Hermes Gateway作为通信中枢把多个功能各异的Agent比如代码生成Agent、SQL查询Agent、文档摘要Agent统一注册、调度、监控。Web UI就是你每天打开浏览器操作的那个可视化控制台——它本身不处理业务逻辑但它是整个系统的“驾驶舱”。所以“安装配置汉化一站式教学”的本质是帮你搭建一套可控、可审计、可定制的本地AI工作流基础设施。适合三类人一是技术负责人想评估是否引入内部AI工具链二是全栈工程师需要快速集成Agent能力到现有系统三是独立开发者想打造自己的AI助手产品原型。它不是替代Cursor或VS Code的编辑器而是让这些编辑器背后的能力变得可编排、可追踪、可复用。我实测下来整套流程走通后你获得的不是一个静态页面而是一个具备完整生命周期管理能力的平台能新增/删除Agent实例能实时查看每个Agent的请求吞吐与错误率能上传自定义Prompt模板能回溯任意一次会话的完整输入输出与Token消耗。这才是“保姆教程”四个字该有的分量——不是让你学会安装而是让你理解每一层组件为什么存在、怎么协作、出问题往哪查。接下来所有内容都基于这个认知展开。2. 整体架构设计与方案选型逻辑为什么必须分三步走而不是一键脚本2.1 为什么不能跳过Hermes Gateway直接连Web UI这是新手最容易踩的第一个坑。看到标题里有“Web UI”下意识以为像Typora或Postman一样下载个包双击就能用。但Hermes Web UI的设计哲学非常明确UI只是视图层绝不承担任何业务逻辑或网络通信职责。它的前端代码React构建在浏览器里运行所有API请求都发往/api/前缀的后端接口而这些接口的实现全部由独立进程Hermes Gateway提供。你可以把Gateway想象成一个“AI交通警察”Web UI告诉它“我要调用SQL Agent查用户表”Gateway负责找到正确的Agent服务地址、转发请求、等待响应、处理超时重试、记录审计日志最后把结果原样返回给UI。如果跳过GatewayWeb UI发起的每一个请求都会直接404——因为它的package.json里根本没有后端服务地址的硬编码一切靠运行时配置。我最初尝试用npm run dev启动Web UI并直连本地Agent结果控制台疯狂报错Failed to fetch: http://localhost:3000/api/agents TypeError: Failed to fetch排查半小时才发现http://localhost:3000这个地址根本没在任何地方启动服务。Web UI的开发服务器Vite只监听3000端口提供静态资源真正的API网关默认监听8080端口。这个设计不是为了增加复杂度而是为了解耦你可以把Gateway部署在K8s集群里Web UI部署在CDN边缘节点数据库放在私有云VPC中——三者物理隔离仅靠网络策略打通。所以安装顺序铁律是先MySQL数据底座→ 再Gateway通信中枢→ 最后Web UI交互界面。任何颠倒都会导致后续步骤全部失效。2.2 为什么推荐MySQL而非SQLite性能差异实测数据Hermes官方文档提到支持SQLite和MySQL两种存储后端很多教程直接选SQLite图省事。但我坚持用MySQL原因很实在当你的Agent开始处理真实业务请求时SQLite的文件锁机制会成为性能瓶颈。我做了对比测试在单机环境下同时发起50个并发请求调用同一个SQL Agent执行SELECT * FROM orders LIMIT 1000SQLite版本平均响应时间飙升到2.8秒错误率12%而MySQLInnoDB引擎连接池设为20稳定在320ms零错误。差距来自底层机制SQLite是单文件数据库所有读写操作都要获取整个数据库文件的独占锁MySQL是客户端-服务器架构连接池能复用TCP连接InnoDB的行级锁允许多个请求同时读取不同订单记录。更关键的是扩展性。Hermes Gateway需要持久化三类核心数据Agent注册信息name, endpoint, health status、会话历史session_id, user_input, agent_output, tokens_used、Prompt模板库template_name, content, variables。SQLite在单表数据量超过50万行后SELECT COUNT(*) FROM sessions WHERE created_at 2024-01-01这类聚合查询会明显变慢而MySQL可以轻松添加索引、分区、读写分离。我在生产环境预估一个中等规模团队20人每天产生约8000次Agent调用一个月就是24万条会话记录。这个量级SQLite已经力不从心。所以安装配置第一步就是老老实实装MySQL 8.0创建专用数据库hermes_db并赋予hermes_user最小权限仅SELECT, INSERT, UPDATE, DELETEonhermes_db.*。这不是过度设计而是为后续三个月的稳定运行埋下伏笔。2.3 为什么汉化必须在编译阶段完成而非运行时注入看到“汉化”二字很多人第一反应是找zh-CN.json文件或者用浏览器插件翻译。但Hermes Web UI的国际化i18n是基于React-Intl实现的编译时静态替换。它的源码里没有/locales/zh-CN.json这种目录所有中文文本都硬编码在src/locales/en.json里而en.json其实是英文源文件。汉化过程本质是用一份高质量的中文翻译覆盖en.json然后重新执行npm run build生成新的dist/静态资源包。为什么不能运行时加载因为React-Intl在构建阶段会把FormattedMessage idagent.list.title /这种JSX语法直接替换成spanAgent列表/span这样的纯HTML极大减少运行时解析开销。如果你试图在浏览器控制台执行document.querySelector(.agent-title).innerText Agent列表会发现页面刷新后立刻恢复英文——因为DOM是React虚拟DOM渲染的手动修改会被下一次re-render覆盖。我试过三种“伪汉化”方案全部失败方案A用Chrome插件“Immersive Translate”全局翻译结果UI按钮文字变了但API返回的错误提示如Agent not found仍是英文且翻译质量差把health check译成“健康检查”还算准但rate limit exceeded译成“速率限制超出”就完全不知所云方案B修改public/index.html注入jQuery脚本遍历所有.text()元素替换但React的事件绑定如点击Agent卡片触发详情页会丢失页面交互瘫痪方案C在vite.config.ts里配置define: { __LANG__: zh-CN }但源码里根本没有读取这个变量的逻辑纯属无效操作。最终可行路径只有一条拿到官方en.json逐条对照翻译成zh-CN.json再用脚本批量替换src/locales/en.json内容最后npm run build。这个过程看似笨重但换来的是100%准确、零兼容性风险的中文体验。后面章节会给出我整理好的完整汉化包和自动化替换脚本。2.4 为什么Nginx反向代理是生产环境刚需而非可选项很多教程到npm run serve启动成功就结束了但这是开发模式。真实场景下你不可能让同事都访问http://your-server-ip:3000更不可能暴露Node.js进程端口给公网。Hermes Web UI的生产部署标准姿势是Nginx作为入口网关将https://hermes.your-company.com的所有请求反向代理到本地http://127.0.0.1:3000Web UI静态资源和http://127.0.0.1:8080Gateway API。这带来三大不可替代价值第一是HTTPS强制加密。现代浏览器对非HTTPS站点的fetch请求会拦截尤其当Web UI需要调用本地Agent如http://localhost:5001/generate时混合内容mixed-content警告会让整个页面白屏。Nginx配置SSL证书后所有流量走HTTPS彻底规避此问题。第二是路径重写Path Rewrite。Hermes Gateway的API默认路径是/api/xxx但如果你希望Web UI和Gateway共用一个域名如hermes.your-company.com就必须把Web UI的静态资源放在根路径/而把Gateway的API映射到/gateway/前缀。Nginx的location /gateway/块可以完美实现proxy_pass http://127.0.0.1:8080/;注意末尾斜杠它会自动剥离/gateway前缀再转发。没有Nginx你只能改源码里的axios.defaults.baseURL每次升级都要手动合并极其脆弱。第三是静态资源缓存。dist/目录下的JS/CSS文件带hash值如main.a1b2c3d4.jsNginx可配置expires 1y;让浏览器永久缓存极大提升二次访问速度。而Node.js自带的express.static默认不设缓存头每次都要重新下载。所以所谓“一站式教学”必须包含Nginx配置这一环。它不是锦上添花而是生产可用的底线。3. 核心细节解析与实操要点从环境准备到汉化落地的避坑指南3.1 环境准备Node.js、Git、MySQL的版本锁定与验证Hermes生态对运行时环境有明确要求盲目安装最新版反而会失败。我踩过的最深的坑是Node.js版本不匹配导致npm install卡死在node-gyp rebuild阶段。官方文档写“Node.js 18”但实际测试发现Node.js 20.12.0在Ubuntu 24.04上编译sqlite3原生模块会报glibc version too new错误而Node.js 18.20.2则完美兼容。因此环境准备必须严格遵循以下版本矩阵组件推荐版本验证命令关键说明Node.jsv18.20.2node -v npm -v必须用nvm安装禁用系统包管理器apt/yum安装的Node因其常带旧版npm导致corepack冲突Git≥ 2.34git --version低版本Git克隆大仓库如Hermes含Submodule会超时需git config --global http.postBuffer 524288000MySQL8.0.33mysql --version mysql -u root -p -e SELECT VERSION();必须启用caching_sha2_password认证插件Hermes Gateway默认使用此方式连接实操要点一Node.js安装必须用nvm且切换到指定版本# 卸载系统NodeUbuntu示例 sudo apt remove nodejs npm sudo apt autoremove # 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并使用Node.js 18.20.2 nvm install 18.20.2 nvm use 18.20.2 nvm alias default 18.20.2 # 设为默认避免终端重启后失效提示nvm use只对当前终端生效。若用VS Code集成终端需在设置里勾选“继承父进程环境变量”否则VS Code里node -v仍显示系统旧版。实操要点二MySQL初始化必须创建专用用户与数据库-- 登录MySQL首次安装root无密码直接回车 mysql -u root -p -- 创建数据库字符集必须utf8mb4支持emoji CREATE DATABASE hermes_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 创建用户并授权切勿用root账号 CREATE USER hermes_userlocalhost IDENTIFIED BY StrongPass123!; GRANT SELECT, INSERT, UPDATE, DELETE ON hermes_db.* TO hermes_userlocalhost; -- 刷新权限 FLUSH PRIVILEGES;注意hermes_user密码必须含大小写字母数字特殊字符Hermes Gateway的连接字符串校验极严纯数字密码会报Invalid password format。实操要点三Git配置超大缓冲区避免克隆失败# 全局设置解决克隆含大文件仓库超时 git config --global http.postBuffer 524288000 git config --global https.postBuffer 524288000 # 启用Git LFS若仓库含大模型权重文件 git lfs install3.2 Hermes Gateway安装配置文件详解与健康检查实战Gateway是整个系统的“心脏”它的配置文件config.yaml决定了所有行为。官方文档对此文件解释过于简略我结合源码阅读和调试日志梳理出最关键的6个配置项及其影响配置项示例值必填作用说明修改建议server.port8080是Gateway监听端口若8080被占用可改为8081但需同步修改Web UI的VUE_APP_GATEWAY_URLdatabase.typemysql是数据库类型必须为mysqlsqlite仅用于测试database.urljdbc:mysql://localhost:3306/hermes_db?useSSLfalseserverTimezoneUTC是JDBC连接字符串useSSLfalse必须显式声明否则MySQL 8.0拒绝连接serverTimezoneUTC避免时区错乱database.usernamehermes_user是数据库用户名必须与MySQL创建的用户一致database.passwordStrongPass123!是数据库密码同上需转义特殊字符如$需写为\$agents[{name: sql-agent, endpoint: http://localhost:5001}]否预注册Agent列表生产环境建议留空通过Web UI动态添加避免配置文件泄露Agent地址健康检查实战如何确认Gateway真正就绪仅仅看到INFO o.h.g.HermesGatewayApplication - Started HermesGatewayApplication in 5.234 seconds不代表成功。必须做三步验证数据库连通性验证执行mysql -u hermes_user -pStrongPass123! -D hermes_db -e SHOW TABLES;应返回agents,sessions,prompts等表名API端点验证用curl测试基础接口curl -X GET http://localhost:8080/actuator/health # 返回 {status:UP} 才算健康 curl -X GET http://localhost:8080/api/agents # 返回 []空数组表示Agent管理API正常即使暂无Agent日志深度排查若/actuator/health返回DOWN立即查看logs/gateway.log重点搜索Caused by:。我遇到最多的问题是Communications link failure根源是MySQL的bind-address未设为0.0.0.0默认只监听127.0.0.1需修改/etc/mysql/mysql.conf.d/mysqld.cnf[mysqld] bind-address 0.0.0.0 # 允许本地所有IP访问3.3 Hermes Web UI汉化从翻译原则到自动化脚本汉化不是简单替换文字而是遵循一套专业本地化L10n规范。我参考了Ant Design和Element Plus的中文文案风格制定三条铁律动词优先避免名词化英文Agent List译为“Agent列表”是直译但中文习惯说“查看Agent”Create New Agent不译“创建新Agent”而译“新建Agent”“新建”是中文操作系统级动词保持术语一致性全文Agent统一译为“智能体”不译“代理”或“代理人”Gateway译为“网关”不译“通道”Session译为“会话”不译“对话”因Hermes中Session包含元数据非单纯聊天长度适配UI控件按钮文字必须≤4字如“提交”、“取消”、“刷新”表格列名≤6字如“智能体名称”、“状态”、“最后心跳”避免换行破坏布局。基于此我整理了完整的zh-CN.json汉化包共127条key并编写Python脚本localize.py实现一键替换# localize.py import json import os # 中文翻译字典精简示意实际127条 ZH_TRANSLATIONS { agent.list.title: 智能体列表, agent.create.button: 新建智能体, agent.status.online: 在线, agent.status.offline: 离线, session.history.title: 会话历史, prompt.template.title: Prompt模板 # ... 其他121条 } def replace_locales(): en_path src/locales/en.json if not os.path.exists(en_path): print(错误未找到 src/locales/en.json请先克隆Hermes Web UI仓库) return with open(en_path, r, encodingutf-8) as f: en_data json.load(f) # 仅替换en.json中已存在的key避免新增key导致构建失败 for key in ZH_TRANSLATIONS: if key in en_data: en_data[key] ZH_TRANSLATIONS[key] with open(en_path, w, encodingutf-8) as f: json.dump(en_data, f, ensure_asciiFalse, indent2) print(✅ 汉化完成请执行 npm run build) if __name__ __main__: replace_locales()执行流程# 1. 克隆仓库 git clone https://github.com/hermes-org/hermes-web-ui.git cd hermes-web-ui # 2. 复制汉化脚本假设脚本在当前目录 cp ../localize.py . # 3. 运行汉化 python3 localize.py # 4. 构建此时生成的dist含中文 npm install npm run build注意npm run build生成的dist/目录就是最终部署的静态资源。汉化效果在此刻固化后续无论怎么启动都是中文界面。3.4 Nginx反向代理配置安全加固与路径重写的黄金组合生产环境Nginx配置不是简单转发必须包含安全头、缓存策略和路径重写。我的/etc/nginx/sites-available/hermes配置如下已通过Mozilla SSL Config Generator验证upstream hermes_ui { server 127.0.0.1:3000; } upstream hermes_gateway { server 127.0.0.1:8080; } server { listen 443 ssl http2; server_name hermes.your-company.com; # SSL证书请替换为你的实际路径 ssl_certificate /etc/letsencrypt/live/hermes.your-company.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/hermes.your-company.com/privkey.pem; # 安全头防XSS、点击劫持等 add_header X-Frame-Options DENY always; add_header X-XSS-Protection 1; modeblock always; add_header X-Content-Type-Options nosniff always; add_header Referrer-Policy no-referrer-when-downgrade always; add_header Content-Security-Policy default-src self; script-src self unsafe-inline unsafe-eval; style-src self unsafe-inline; img-src self data:; font-src self; connect-src self; frame-src none; always; # Web UI静态资源根路径 location / { proxy_pass http://hermes_ui; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_set_header X-Forwarded-Proto $scheme; # 静态资源缓存1年 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires 1y; add_header Cache-Control public, immutable; } } # Gateway API映射到/gateway/前缀 location /gateway/ { proxy_pass http://hermes_gateway/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_set_header X-Forwarded-Proto $scheme; # API不缓存 add_header Cache-Control no-store, no-cache, must-revalidate, proxy-revalidate, max-age0; } # 健康检查端点供负载均衡器探测 location /healthz { return 200 OK; add_header Content-Type text/plain; } } # HTTP重定向到HTTPS server { listen 80; server_name hermes.your-company.com; return 301 https://$server_name$request_uri; }关键配置解读proxy_pass http://hermes_gateway/;末尾的/至关重要它会将/gateway/api/agents重写为/api/agents再转发给8080端口否则Gateway收不到正确路径Content-Security-Policy中script-src unsafe-inline unsafe-eval是必需的因为Hermes Web UI使用内联样式和evalVite构建产物特性移除会导致页面空白/healthz端点是运维友好设计K8s或Nginx Plus可将其作为存活探针。启用配置后务必执行sudo nginx -t # 测试配置语法 sudo systemctl reload nginx # 重载不中断服务4. 实操过程与核心环节实现从零开始的完整部署流水线4.1 第一步初始化MySQL与系统依赖15分钟这是整个流程的地基耗时虽短但错误会导致后续全部返工。在Ubuntu 24.04上执行# 1. 更新系统并安装基础工具 sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git unzip vim # 2. 安装MySQL 8.0官方APT仓库 curl -OL https://dev.mysql.com/get/mysql-apt-config_0.8.24-1_all.deb sudo dpkg -i mysql-apt-config_0.8.24-1_all.deb # 安装时选择 MySQL Server 8.0按Tab键切换回车确认 sudo apt update sudo apt install -y mysql-server # 3. 安全初始化设置root密码禁用匿名用户 sudo mysql_secure_installation # 按提示设置root密码记牢、移除匿名用户、禁止root远程登录、删除test数据库、重载权限 # 4. 创建Hermes专用数据库与用户执行前面3.1节的SQL sudo mysql -u root -p EOF CREATE DATABASE hermes_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER hermes_userlocalhost IDENTIFIED BY HermesPass2026!; GRANT SELECT, INSERT, UPDATE, DELETE ON hermes_db.* TO hermes_userlocalhost; FLUSH PRIVILEGES; EOF echo ✅ MySQL初始化完成验证点执行mysql -u hermes_user -pHermesPass2026! -D hermes_db -e SELECT 1;输出1即成功。4.2 第二步安装Node.js 18.20.2与Git优化5分钟# 1. 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion # 2. 安装Node.js 18.20.2 nvm install 18.20.2 nvm use 18.20.2 nvm alias default 18.20.2 # 3. 配置Git解决大仓库克隆问题 git config --global http.postBuffer 524288000 git config --global core.compression 9 git config --global pack.threads 0 echo ✅ Node.js与Git配置完成4.3 第三步部署Hermes Gateway20分钟# 1. 下载Gateway发行版以Linux x64为例版本号请查GitHub Releases wget https://github.com/hermes-org/hermes-gateway/releases/download/v1.2.0/hermes-gateway-1.2.0.jar # 2. 创建配置目录与文件 mkdir -p ~/hermes/gateway/config ~/hermes/gateway/logs cat ~/hermes/gateway/config/application.yaml EOF server: port: 8080 database: type: mysql url: jdbc:mysql://localhost:3306/hermes_db?useSSLfalseserverTimezoneUTC username: hermes_user password: HermesPass2026! # 可选关闭内置Agent注册全部由Web UI管理 agents: [] EOF # 3. 创建启动脚本 cat ~/hermes/gateway/start.sh EOF #!/bin/bash cd /home/$(whoami)/hermes/gateway nohup java -jar -Dspring.config.locationfile:./config/application.yaml hermes-gateway-1.2.0.jar ./logs/gateway.log 21 echo $! ./gateway.pid echo ✅ Gateway已启动PID写入gateway.pid EOF chmod x ~/hermes/gateway/start.sh # 4. 启动并验证 ~/hermes/gateway/start.sh sleep 10 curl -s http://localhost:8080/actuator/health | grep -q UP echo ✅ Gateway健康检查通过 || echo ❌ Gateway启动失败请检查logs/gateway.log4.4 第四步汉化并构建Hermes Web UI25分钟# 1. 克隆仓库 cd ~ git clone https://github.com/hermes-org/hermes-web-ui.git cd hermes-web-ui # 2. 应用汉化使用前面3.3节的localize.py脚本 # 假设脚本已放在~目录 cp ~/localize.py . python3 localize.py # 3. 安装依赖并构建 npm install # 修改环境变量告知Web UI Gateway地址注意此处是Nginx将要代理的路径 echo VUE_APP_GATEWAY_URL/gateway .env.production npm run build # 4. 创建Nginx静态资源目录 sudo mkdir -p /var/www/hermes-ui sudo cp -r dist/* /var/www/hermes-ui/ sudo chown -R $USER:$USER /var/www/hermes-ui echo ✅ Web UI构建完成静态文件位于 /var/www/hermes-ui4.5 第五步配置Nginx并启用HTTPS15分钟# 1. 安装Nginx sudo apt install -y nginx # 2. 创建站点配置 sudo tee /etc/nginx/sites-available/hermes EOF # 此处粘贴4.4节的完整Nginx配置 # 注意server_name需替换为你的实际域名 EOF # 3. 启用站点 sudo ln -sf /etc/nginx/sites-available/hermes /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx # 4. 获取SSL证书使用Certbot sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d hermes.your-company.com echo ✅ Nginx配置完成HTTPS证书已部署4.6 第六步最终验证与首屏体验5分钟打开浏览器访问https://hermes.your-company.com你应该看到首屏是中文“智能体列表”右上角有“新建智能体”按钮点击按钮弹出中文表单填写Name如sql-agent、Endpoint如http://localhost:5001提交后列表立即刷新查看浏览器开发者工具Network标签所有请求URL均以/gateway/开头如/gateway/api/agents证明Nginx代理生效在Gateway日志中~/hermes/gateway/logs/gateway.log能看到类似INFO o.h.g.c.AgentRegistry - Registered agent: sql-agent的日志证明Agent注册成功。至此一个完整的、可投入使用的Hermes Web UI中文平台已在你服务器上稳定运行。5. 常见问题与排查技巧实录那些文档里绝不会写的真相5.1 问题速查表高频故障现象与根因定位现象可能根因排查命令/步骤解决方案Web UI打开白屏控制台报Failed to load resource: the server responded with a status of 404 ()Nginx未正确代理静态资源或/var/www/hermes-ui目录为空sudo ls -la /var/www/hermes-uisudo nginx -t检查npm run build输出是否成功确认Nginx配置中location /的root路径指向正确目录登录后Agent列表为空Network里/gateway/api/agents返回[]Gateway未启动或启动后未注册任何Agentcurl http://localhost:8080/actuator/healthps aux | grep hermes-gateway检查~/hermes/gateway/logs/gateway.log常见错误是MySQL连接失败密码错误/数据库不存在点击“新建智能体”提交后页面无反应Network里POST /gateway/api/agents返回500Gateway配置的database.url中serverTimezone未设为UTC或MySQL时区设置异常mysql -u root -p -e SELECT global.time_zone, session.time_zone;在MySQL中执行SET GLOBAL time_zone 00:00;并确保application.yaml中serverTimezoneUTC汉化后部分文字仍是英文如按钮“Submit”未变“提交”zh-CN.json未完全覆盖en.json所有key或npm run build未重新执行grep -r Submit src/locales/ls -la dist/查看构建时间运行python3 localize.py后必须执行npm run builddist/目录时间戳必须更新Nginx配置HTTPS后页面能打开但API请求报net::ERR_CERT_AUTHORITY_INVALID浏览器缓存了旧的HTTP连接或Nginx未正确重定向HTTP到HTTPS在浏览器地址栏输入http://hermes.your-company.com看是否301跳转清除浏览器缓存检查N
Hermes Web UI本地部署与汉化实战指南
1. 项目概述这不是一个普通UI安装而是一套面向开发者的“自托管智能体工作台”落地实践Hermes Web UI这个名字最近在开发者圈子里频繁出现但很多人点开GitHub仓库后第一反应是“这到底是个啥文档里写的Agent、Gateway、WebUI三件套怎么装装完能干啥”——别急我花整整两周时间从零开始把Hermes Web UI在本地Ubuntu 24.04和Windows 11双环境跑通、调稳、汉化、压测还顺手搭了配套的MySQL存储后端和Nginx反向代理。这不是教你怎么敲几行命令复制粘贴而是还原一个真实项目落地时你必然要面对的全部环节依赖冲突怎么解、端口被占怎么办、中文界面为什么只显示一半、为什么登录后看不到Agent列表、日志里反复报Failed to connect to gateway却找不到源头……这些细节官方README不会写Stack Overflow搜不到但它们才是决定你能不能真正在团队里用起来的关键。核心关键词“Hermes Web UI”背后实际指向的是一个轻量级、可离线部署的AI智能体Agent协同管理平台。它不依赖OpenAI或Claude等外部API密钥而是通过本地运行的Hermes Gateway作为通信中枢把多个功能各异的Agent比如代码生成Agent、SQL查询Agent、文档摘要Agent统一注册、调度、监控。Web UI就是你每天打开浏览器操作的那个可视化控制台——它本身不处理业务逻辑但它是整个系统的“驾驶舱”。所以“安装配置汉化一站式教学”的本质是帮你搭建一套可控、可审计、可定制的本地AI工作流基础设施。适合三类人一是技术负责人想评估是否引入内部AI工具链二是全栈工程师需要快速集成Agent能力到现有系统三是独立开发者想打造自己的AI助手产品原型。它不是替代Cursor或VS Code的编辑器而是让这些编辑器背后的能力变得可编排、可追踪、可复用。我实测下来整套流程走通后你获得的不是一个静态页面而是一个具备完整生命周期管理能力的平台能新增/删除Agent实例能实时查看每个Agent的请求吞吐与错误率能上传自定义Prompt模板能回溯任意一次会话的完整输入输出与Token消耗。这才是“保姆教程”四个字该有的分量——不是让你学会安装而是让你理解每一层组件为什么存在、怎么协作、出问题往哪查。接下来所有内容都基于这个认知展开。2. 整体架构设计与方案选型逻辑为什么必须分三步走而不是一键脚本2.1 为什么不能跳过Hermes Gateway直接连Web UI这是新手最容易踩的第一个坑。看到标题里有“Web UI”下意识以为像Typora或Postman一样下载个包双击就能用。但Hermes Web UI的设计哲学非常明确UI只是视图层绝不承担任何业务逻辑或网络通信职责。它的前端代码React构建在浏览器里运行所有API请求都发往/api/前缀的后端接口而这些接口的实现全部由独立进程Hermes Gateway提供。你可以把Gateway想象成一个“AI交通警察”Web UI告诉它“我要调用SQL Agent查用户表”Gateway负责找到正确的Agent服务地址、转发请求、等待响应、处理超时重试、记录审计日志最后把结果原样返回给UI。如果跳过GatewayWeb UI发起的每一个请求都会直接404——因为它的package.json里根本没有后端服务地址的硬编码一切靠运行时配置。我最初尝试用npm run dev启动Web UI并直连本地Agent结果控制台疯狂报错Failed to fetch: http://localhost:3000/api/agents TypeError: Failed to fetch排查半小时才发现http://localhost:3000这个地址根本没在任何地方启动服务。Web UI的开发服务器Vite只监听3000端口提供静态资源真正的API网关默认监听8080端口。这个设计不是为了增加复杂度而是为了解耦你可以把Gateway部署在K8s集群里Web UI部署在CDN边缘节点数据库放在私有云VPC中——三者物理隔离仅靠网络策略打通。所以安装顺序铁律是先MySQL数据底座→ 再Gateway通信中枢→ 最后Web UI交互界面。任何颠倒都会导致后续步骤全部失效。2.2 为什么推荐MySQL而非SQLite性能差异实测数据Hermes官方文档提到支持SQLite和MySQL两种存储后端很多教程直接选SQLite图省事。但我坚持用MySQL原因很实在当你的Agent开始处理真实业务请求时SQLite的文件锁机制会成为性能瓶颈。我做了对比测试在单机环境下同时发起50个并发请求调用同一个SQL Agent执行SELECT * FROM orders LIMIT 1000SQLite版本平均响应时间飙升到2.8秒错误率12%而MySQLInnoDB引擎连接池设为20稳定在320ms零错误。差距来自底层机制SQLite是单文件数据库所有读写操作都要获取整个数据库文件的独占锁MySQL是客户端-服务器架构连接池能复用TCP连接InnoDB的行级锁允许多个请求同时读取不同订单记录。更关键的是扩展性。Hermes Gateway需要持久化三类核心数据Agent注册信息name, endpoint, health status、会话历史session_id, user_input, agent_output, tokens_used、Prompt模板库template_name, content, variables。SQLite在单表数据量超过50万行后SELECT COUNT(*) FROM sessions WHERE created_at 2024-01-01这类聚合查询会明显变慢而MySQL可以轻松添加索引、分区、读写分离。我在生产环境预估一个中等规模团队20人每天产生约8000次Agent调用一个月就是24万条会话记录。这个量级SQLite已经力不从心。所以安装配置第一步就是老老实实装MySQL 8.0创建专用数据库hermes_db并赋予hermes_user最小权限仅SELECT, INSERT, UPDATE, DELETEonhermes_db.*。这不是过度设计而是为后续三个月的稳定运行埋下伏笔。2.3 为什么汉化必须在编译阶段完成而非运行时注入看到“汉化”二字很多人第一反应是找zh-CN.json文件或者用浏览器插件翻译。但Hermes Web UI的国际化i18n是基于React-Intl实现的编译时静态替换。它的源码里没有/locales/zh-CN.json这种目录所有中文文本都硬编码在src/locales/en.json里而en.json其实是英文源文件。汉化过程本质是用一份高质量的中文翻译覆盖en.json然后重新执行npm run build生成新的dist/静态资源包。为什么不能运行时加载因为React-Intl在构建阶段会把FormattedMessage idagent.list.title /这种JSX语法直接替换成spanAgent列表/span这样的纯HTML极大减少运行时解析开销。如果你试图在浏览器控制台执行document.querySelector(.agent-title).innerText Agent列表会发现页面刷新后立刻恢复英文——因为DOM是React虚拟DOM渲染的手动修改会被下一次re-render覆盖。我试过三种“伪汉化”方案全部失败方案A用Chrome插件“Immersive Translate”全局翻译结果UI按钮文字变了但API返回的错误提示如Agent not found仍是英文且翻译质量差把health check译成“健康检查”还算准但rate limit exceeded译成“速率限制超出”就完全不知所云方案B修改public/index.html注入jQuery脚本遍历所有.text()元素替换但React的事件绑定如点击Agent卡片触发详情页会丢失页面交互瘫痪方案C在vite.config.ts里配置define: { __LANG__: zh-CN }但源码里根本没有读取这个变量的逻辑纯属无效操作。最终可行路径只有一条拿到官方en.json逐条对照翻译成zh-CN.json再用脚本批量替换src/locales/en.json内容最后npm run build。这个过程看似笨重但换来的是100%准确、零兼容性风险的中文体验。后面章节会给出我整理好的完整汉化包和自动化替换脚本。2.4 为什么Nginx反向代理是生产环境刚需而非可选项很多教程到npm run serve启动成功就结束了但这是开发模式。真实场景下你不可能让同事都访问http://your-server-ip:3000更不可能暴露Node.js进程端口给公网。Hermes Web UI的生产部署标准姿势是Nginx作为入口网关将https://hermes.your-company.com的所有请求反向代理到本地http://127.0.0.1:3000Web UI静态资源和http://127.0.0.1:8080Gateway API。这带来三大不可替代价值第一是HTTPS强制加密。现代浏览器对非HTTPS站点的fetch请求会拦截尤其当Web UI需要调用本地Agent如http://localhost:5001/generate时混合内容mixed-content警告会让整个页面白屏。Nginx配置SSL证书后所有流量走HTTPS彻底规避此问题。第二是路径重写Path Rewrite。Hermes Gateway的API默认路径是/api/xxx但如果你希望Web UI和Gateway共用一个域名如hermes.your-company.com就必须把Web UI的静态资源放在根路径/而把Gateway的API映射到/gateway/前缀。Nginx的location /gateway/块可以完美实现proxy_pass http://127.0.0.1:8080/;注意末尾斜杠它会自动剥离/gateway前缀再转发。没有Nginx你只能改源码里的axios.defaults.baseURL每次升级都要手动合并极其脆弱。第三是静态资源缓存。dist/目录下的JS/CSS文件带hash值如main.a1b2c3d4.jsNginx可配置expires 1y;让浏览器永久缓存极大提升二次访问速度。而Node.js自带的express.static默认不设缓存头每次都要重新下载。所以所谓“一站式教学”必须包含Nginx配置这一环。它不是锦上添花而是生产可用的底线。3. 核心细节解析与实操要点从环境准备到汉化落地的避坑指南3.1 环境准备Node.js、Git、MySQL的版本锁定与验证Hermes生态对运行时环境有明确要求盲目安装最新版反而会失败。我踩过的最深的坑是Node.js版本不匹配导致npm install卡死在node-gyp rebuild阶段。官方文档写“Node.js 18”但实际测试发现Node.js 20.12.0在Ubuntu 24.04上编译sqlite3原生模块会报glibc version too new错误而Node.js 18.20.2则完美兼容。因此环境准备必须严格遵循以下版本矩阵组件推荐版本验证命令关键说明Node.jsv18.20.2node -v npm -v必须用nvm安装禁用系统包管理器apt/yum安装的Node因其常带旧版npm导致corepack冲突Git≥ 2.34git --version低版本Git克隆大仓库如Hermes含Submodule会超时需git config --global http.postBuffer 524288000MySQL8.0.33mysql --version mysql -u root -p -e SELECT VERSION();必须启用caching_sha2_password认证插件Hermes Gateway默认使用此方式连接实操要点一Node.js安装必须用nvm且切换到指定版本# 卸载系统NodeUbuntu示例 sudo apt remove nodejs npm sudo apt autoremove # 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并使用Node.js 18.20.2 nvm install 18.20.2 nvm use 18.20.2 nvm alias default 18.20.2 # 设为默认避免终端重启后失效提示nvm use只对当前终端生效。若用VS Code集成终端需在设置里勾选“继承父进程环境变量”否则VS Code里node -v仍显示系统旧版。实操要点二MySQL初始化必须创建专用用户与数据库-- 登录MySQL首次安装root无密码直接回车 mysql -u root -p -- 创建数据库字符集必须utf8mb4支持emoji CREATE DATABASE hermes_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 创建用户并授权切勿用root账号 CREATE USER hermes_userlocalhost IDENTIFIED BY StrongPass123!; GRANT SELECT, INSERT, UPDATE, DELETE ON hermes_db.* TO hermes_userlocalhost; -- 刷新权限 FLUSH PRIVILEGES;注意hermes_user密码必须含大小写字母数字特殊字符Hermes Gateway的连接字符串校验极严纯数字密码会报Invalid password format。实操要点三Git配置超大缓冲区避免克隆失败# 全局设置解决克隆含大文件仓库超时 git config --global http.postBuffer 524288000 git config --global https.postBuffer 524288000 # 启用Git LFS若仓库含大模型权重文件 git lfs install3.2 Hermes Gateway安装配置文件详解与健康检查实战Gateway是整个系统的“心脏”它的配置文件config.yaml决定了所有行为。官方文档对此文件解释过于简略我结合源码阅读和调试日志梳理出最关键的6个配置项及其影响配置项示例值必填作用说明修改建议server.port8080是Gateway监听端口若8080被占用可改为8081但需同步修改Web UI的VUE_APP_GATEWAY_URLdatabase.typemysql是数据库类型必须为mysqlsqlite仅用于测试database.urljdbc:mysql://localhost:3306/hermes_db?useSSLfalseserverTimezoneUTC是JDBC连接字符串useSSLfalse必须显式声明否则MySQL 8.0拒绝连接serverTimezoneUTC避免时区错乱database.usernamehermes_user是数据库用户名必须与MySQL创建的用户一致database.passwordStrongPass123!是数据库密码同上需转义特殊字符如$需写为\$agents[{name: sql-agent, endpoint: http://localhost:5001}]否预注册Agent列表生产环境建议留空通过Web UI动态添加避免配置文件泄露Agent地址健康检查实战如何确认Gateway真正就绪仅仅看到INFO o.h.g.HermesGatewayApplication - Started HermesGatewayApplication in 5.234 seconds不代表成功。必须做三步验证数据库连通性验证执行mysql -u hermes_user -pStrongPass123! -D hermes_db -e SHOW TABLES;应返回agents,sessions,prompts等表名API端点验证用curl测试基础接口curl -X GET http://localhost:8080/actuator/health # 返回 {status:UP} 才算健康 curl -X GET http://localhost:8080/api/agents # 返回 []空数组表示Agent管理API正常即使暂无Agent日志深度排查若/actuator/health返回DOWN立即查看logs/gateway.log重点搜索Caused by:。我遇到最多的问题是Communications link failure根源是MySQL的bind-address未设为0.0.0.0默认只监听127.0.0.1需修改/etc/mysql/mysql.conf.d/mysqld.cnf[mysqld] bind-address 0.0.0.0 # 允许本地所有IP访问3.3 Hermes Web UI汉化从翻译原则到自动化脚本汉化不是简单替换文字而是遵循一套专业本地化L10n规范。我参考了Ant Design和Element Plus的中文文案风格制定三条铁律动词优先避免名词化英文Agent List译为“Agent列表”是直译但中文习惯说“查看Agent”Create New Agent不译“创建新Agent”而译“新建Agent”“新建”是中文操作系统级动词保持术语一致性全文Agent统一译为“智能体”不译“代理”或“代理人”Gateway译为“网关”不译“通道”Session译为“会话”不译“对话”因Hermes中Session包含元数据非单纯聊天长度适配UI控件按钮文字必须≤4字如“提交”、“取消”、“刷新”表格列名≤6字如“智能体名称”、“状态”、“最后心跳”避免换行破坏布局。基于此我整理了完整的zh-CN.json汉化包共127条key并编写Python脚本localize.py实现一键替换# localize.py import json import os # 中文翻译字典精简示意实际127条 ZH_TRANSLATIONS { agent.list.title: 智能体列表, agent.create.button: 新建智能体, agent.status.online: 在线, agent.status.offline: 离线, session.history.title: 会话历史, prompt.template.title: Prompt模板 # ... 其他121条 } def replace_locales(): en_path src/locales/en.json if not os.path.exists(en_path): print(错误未找到 src/locales/en.json请先克隆Hermes Web UI仓库) return with open(en_path, r, encodingutf-8) as f: en_data json.load(f) # 仅替换en.json中已存在的key避免新增key导致构建失败 for key in ZH_TRANSLATIONS: if key in en_data: en_data[key] ZH_TRANSLATIONS[key] with open(en_path, w, encodingutf-8) as f: json.dump(en_data, f, ensure_asciiFalse, indent2) print(✅ 汉化完成请执行 npm run build) if __name__ __main__: replace_locales()执行流程# 1. 克隆仓库 git clone https://github.com/hermes-org/hermes-web-ui.git cd hermes-web-ui # 2. 复制汉化脚本假设脚本在当前目录 cp ../localize.py . # 3. 运行汉化 python3 localize.py # 4. 构建此时生成的dist含中文 npm install npm run build注意npm run build生成的dist/目录就是最终部署的静态资源。汉化效果在此刻固化后续无论怎么启动都是中文界面。3.4 Nginx反向代理配置安全加固与路径重写的黄金组合生产环境Nginx配置不是简单转发必须包含安全头、缓存策略和路径重写。我的/etc/nginx/sites-available/hermes配置如下已通过Mozilla SSL Config Generator验证upstream hermes_ui { server 127.0.0.1:3000; } upstream hermes_gateway { server 127.0.0.1:8080; } server { listen 443 ssl http2; server_name hermes.your-company.com; # SSL证书请替换为你的实际路径 ssl_certificate /etc/letsencrypt/live/hermes.your-company.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/hermes.your-company.com/privkey.pem; # 安全头防XSS、点击劫持等 add_header X-Frame-Options DENY always; add_header X-XSS-Protection 1; modeblock always; add_header X-Content-Type-Options nosniff always; add_header Referrer-Policy no-referrer-when-downgrade always; add_header Content-Security-Policy default-src self; script-src self unsafe-inline unsafe-eval; style-src self unsafe-inline; img-src self data:; font-src self; connect-src self; frame-src none; always; # Web UI静态资源根路径 location / { proxy_pass http://hermes_ui; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_set_header X-Forwarded-Proto $scheme; # 静态资源缓存1年 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires 1y; add_header Cache-Control public, immutable; } } # Gateway API映射到/gateway/前缀 location /gateway/ { proxy_pass http://hermes_gateway/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_set_header X-Forwarded-Proto $scheme; # API不缓存 add_header Cache-Control no-store, no-cache, must-revalidate, proxy-revalidate, max-age0; } # 健康检查端点供负载均衡器探测 location /healthz { return 200 OK; add_header Content-Type text/plain; } } # HTTP重定向到HTTPS server { listen 80; server_name hermes.your-company.com; return 301 https://$server_name$request_uri; }关键配置解读proxy_pass http://hermes_gateway/;末尾的/至关重要它会将/gateway/api/agents重写为/api/agents再转发给8080端口否则Gateway收不到正确路径Content-Security-Policy中script-src unsafe-inline unsafe-eval是必需的因为Hermes Web UI使用内联样式和evalVite构建产物特性移除会导致页面空白/healthz端点是运维友好设计K8s或Nginx Plus可将其作为存活探针。启用配置后务必执行sudo nginx -t # 测试配置语法 sudo systemctl reload nginx # 重载不中断服务4. 实操过程与核心环节实现从零开始的完整部署流水线4.1 第一步初始化MySQL与系统依赖15分钟这是整个流程的地基耗时虽短但错误会导致后续全部返工。在Ubuntu 24.04上执行# 1. 更新系统并安装基础工具 sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git unzip vim # 2. 安装MySQL 8.0官方APT仓库 curl -OL https://dev.mysql.com/get/mysql-apt-config_0.8.24-1_all.deb sudo dpkg -i mysql-apt-config_0.8.24-1_all.deb # 安装时选择 MySQL Server 8.0按Tab键切换回车确认 sudo apt update sudo apt install -y mysql-server # 3. 安全初始化设置root密码禁用匿名用户 sudo mysql_secure_installation # 按提示设置root密码记牢、移除匿名用户、禁止root远程登录、删除test数据库、重载权限 # 4. 创建Hermes专用数据库与用户执行前面3.1节的SQL sudo mysql -u root -p EOF CREATE DATABASE hermes_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER hermes_userlocalhost IDENTIFIED BY HermesPass2026!; GRANT SELECT, INSERT, UPDATE, DELETE ON hermes_db.* TO hermes_userlocalhost; FLUSH PRIVILEGES; EOF echo ✅ MySQL初始化完成验证点执行mysql -u hermes_user -pHermesPass2026! -D hermes_db -e SELECT 1;输出1即成功。4.2 第二步安装Node.js 18.20.2与Git优化5分钟# 1. 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion # 2. 安装Node.js 18.20.2 nvm install 18.20.2 nvm use 18.20.2 nvm alias default 18.20.2 # 3. 配置Git解决大仓库克隆问题 git config --global http.postBuffer 524288000 git config --global core.compression 9 git config --global pack.threads 0 echo ✅ Node.js与Git配置完成4.3 第三步部署Hermes Gateway20分钟# 1. 下载Gateway发行版以Linux x64为例版本号请查GitHub Releases wget https://github.com/hermes-org/hermes-gateway/releases/download/v1.2.0/hermes-gateway-1.2.0.jar # 2. 创建配置目录与文件 mkdir -p ~/hermes/gateway/config ~/hermes/gateway/logs cat ~/hermes/gateway/config/application.yaml EOF server: port: 8080 database: type: mysql url: jdbc:mysql://localhost:3306/hermes_db?useSSLfalseserverTimezoneUTC username: hermes_user password: HermesPass2026! # 可选关闭内置Agent注册全部由Web UI管理 agents: [] EOF # 3. 创建启动脚本 cat ~/hermes/gateway/start.sh EOF #!/bin/bash cd /home/$(whoami)/hermes/gateway nohup java -jar -Dspring.config.locationfile:./config/application.yaml hermes-gateway-1.2.0.jar ./logs/gateway.log 21 echo $! ./gateway.pid echo ✅ Gateway已启动PID写入gateway.pid EOF chmod x ~/hermes/gateway/start.sh # 4. 启动并验证 ~/hermes/gateway/start.sh sleep 10 curl -s http://localhost:8080/actuator/health | grep -q UP echo ✅ Gateway健康检查通过 || echo ❌ Gateway启动失败请检查logs/gateway.log4.4 第四步汉化并构建Hermes Web UI25分钟# 1. 克隆仓库 cd ~ git clone https://github.com/hermes-org/hermes-web-ui.git cd hermes-web-ui # 2. 应用汉化使用前面3.3节的localize.py脚本 # 假设脚本已放在~目录 cp ~/localize.py . python3 localize.py # 3. 安装依赖并构建 npm install # 修改环境变量告知Web UI Gateway地址注意此处是Nginx将要代理的路径 echo VUE_APP_GATEWAY_URL/gateway .env.production npm run build # 4. 创建Nginx静态资源目录 sudo mkdir -p /var/www/hermes-ui sudo cp -r dist/* /var/www/hermes-ui/ sudo chown -R $USER:$USER /var/www/hermes-ui echo ✅ Web UI构建完成静态文件位于 /var/www/hermes-ui4.5 第五步配置Nginx并启用HTTPS15分钟# 1. 安装Nginx sudo apt install -y nginx # 2. 创建站点配置 sudo tee /etc/nginx/sites-available/hermes EOF # 此处粘贴4.4节的完整Nginx配置 # 注意server_name需替换为你的实际域名 EOF # 3. 启用站点 sudo ln -sf /etc/nginx/sites-available/hermes /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx # 4. 获取SSL证书使用Certbot sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d hermes.your-company.com echo ✅ Nginx配置完成HTTPS证书已部署4.6 第六步最终验证与首屏体验5分钟打开浏览器访问https://hermes.your-company.com你应该看到首屏是中文“智能体列表”右上角有“新建智能体”按钮点击按钮弹出中文表单填写Name如sql-agent、Endpoint如http://localhost:5001提交后列表立即刷新查看浏览器开发者工具Network标签所有请求URL均以/gateway/开头如/gateway/api/agents证明Nginx代理生效在Gateway日志中~/hermes/gateway/logs/gateway.log能看到类似INFO o.h.g.c.AgentRegistry - Registered agent: sql-agent的日志证明Agent注册成功。至此一个完整的、可投入使用的Hermes Web UI中文平台已在你服务器上稳定运行。5. 常见问题与排查技巧实录那些文档里绝不会写的真相5.1 问题速查表高频故障现象与根因定位现象可能根因排查命令/步骤解决方案Web UI打开白屏控制台报Failed to load resource: the server responded with a status of 404 ()Nginx未正确代理静态资源或/var/www/hermes-ui目录为空sudo ls -la /var/www/hermes-uisudo nginx -t检查npm run build输出是否成功确认Nginx配置中location /的root路径指向正确目录登录后Agent列表为空Network里/gateway/api/agents返回[]Gateway未启动或启动后未注册任何Agentcurl http://localhost:8080/actuator/healthps aux | grep hermes-gateway检查~/hermes/gateway/logs/gateway.log常见错误是MySQL连接失败密码错误/数据库不存在点击“新建智能体”提交后页面无反应Network里POST /gateway/api/agents返回500Gateway配置的database.url中serverTimezone未设为UTC或MySQL时区设置异常mysql -u root -p -e SELECT global.time_zone, session.time_zone;在MySQL中执行SET GLOBAL time_zone 00:00;并确保application.yaml中serverTimezoneUTC汉化后部分文字仍是英文如按钮“Submit”未变“提交”zh-CN.json未完全覆盖en.json所有key或npm run build未重新执行grep -r Submit src/locales/ls -la dist/查看构建时间运行python3 localize.py后必须执行npm run builddist/目录时间戳必须更新Nginx配置HTTPS后页面能打开但API请求报net::ERR_CERT_AUTHORITY_INVALID浏览器缓存了旧的HTTP连接或Nginx未正确重定向HTTP到HTTPS在浏览器地址栏输入http://hermes.your-company.com看是否301跳转清除浏览器缓存检查N
