[{"data":1,"prerenderedAt":514},["ShallowReactive",2],{"\u002F2026\u002F10004-weixin-hermes-bot":3,"surround-\u002F2026\u002F10004-weixin-hermes-bot":503},{"id":4,"title":5,"body":6,"categories":469,"date":471,"description":472,"draft":473,"extension":474,"hidden":473,"image":475,"meta":476,"navigation":478,"path":479,"permalink":480,"published":480,"readingTime":481,"recommend":486,"references":487,"seo":492,"sitemap":493,"stem":494,"tags":495,"type":501,"updated":471,"__hash__":502},"content\u002Fposts\u002F2026\u002F10004-weixin-hermes-bot.md","把微信变成家庭运维入口:树莓派部署 Hermes 微信机器人全记录",{"type":7,"value":8,"toc":450},"minimark",[9,13,17,20,28,39,52,55,121,128,132,137,140,144,148,151,154,158,165,176,199,203,218,224,228,234,248,251,254,258,264,272,285,289,298,310,316,319,329,367,371,374,399,402,405,426,429,437,440,443],[10,11,12],"h3",{"id":12},"前言",[14,15,16],"p",{},"家里跑着一堆设备和服务:NAS、软路由、VPS、各种 Docker 容器。我一直想要一个最懒的运维入口——躺在沙发上掏手机,在微信里问一句\"NAS 还活着吗\",机器人把状态丢回来。",[14,18,19],{},"听起来很简单,但有个绕不开的现实问题:",[21,22,25],"alert",{"title":23,"type":24},"没有公网 IPv4 怎么办?","question",[14,26,27],{},"家里宽带只有 IPv6 公网,传统的 Webhook 方案(微信事件 → 推送到你的服务器)需要入站可达,IPv4-only 的网络环境下根本进不来。",[14,29,30,31,38],{},"翻了一圈方案,最后选了 ",[32,33,37],"a",{"href":34,"rel":35},"https:\u002F\u002Fhermesagent.org.cn\u002F",[36],"nofollow","Hermes Agent"," 的微信网关,原因就一个:",[21,40,44],{"title":41,"type":42,":card":43},"核心结论","tip","true",[14,45,46,47,51],{},"Hermes 的微信适配器基于腾讯 iLink Bot API,走的是",[48,49,50],"strong",{},"长轮询","——网关主动向外拉消息,不需要公网 IPv4、不需要反向代理、不需要开放任何入站端口,服务器能出网就行。",[10,53,54],{"id":54},"部署环境",[56,57,58,71],"table",{},[59,60,61],"thead",{},[62,63,64,68],"tr",{},[65,66,67],"th",{},"项目",[65,69,70],{},"值",[72,73,74,83,91,102,113],"tbody",{},[62,75,76,80],{},[77,78,79],"td",{},"设备",[77,81,82],{},"树莓派 4B(aarch64)",[62,84,85,88],{},[77,86,87],{},"系统",[77,89,90],{},"Ubuntu,Python 3.11",[62,92,93,96],{},[77,94,95],{},"局域网地址",[77,97,98],{},[99,100,101],"code",{"code":101},"192.168.x.x",[62,103,104,107],{},[77,105,106],{},"DDNS",[77,108,109,112],{},[99,110,111],{"code":111},"pi.example.com","(AAAA 记录,仅作管理入口)",[62,114,115,118],{},[77,116,117],{},"公网能力",[77,119,120],{},"IPv6 公网,无公网 IPv4",[14,122,123,124,127],{},"DDNS 域名在这个方案里",[48,125,126],{},"不是必需品",",只是留着以后管理面板用。微信消息链路完全不依赖它。",[10,129,131],{"id":130},"开搞部署全流程","开搞:部署全流程",[133,134,136],"h4",{"id":135},"_1-建一个专用用户","1. 建一个专用用户",[14,138,139],{},"机器人 7x24 常驻,别和自己的登录用户混在一起:",[141,142],"copy",{"code":143},"sudo adduser --system --group --home \u002Fopt\u002Fhermes hermes",[133,145,147],{"id":146},"_2-装基础依赖","2. 装基础依赖",[141,149],{"code":150},"sudo apt update && sudo apt install -y curl ca-certificates git python3 python3-venv python3-pip ripgrep",[14,152,153],{},"Node.js 只有浏览器自动化等可选组件才用得到,单纯部署微信网关可以不装。",[133,155,157],{"id":156},"_3-以服务用户安装-hermes","3. 以服务用户安装 Hermes",[14,159,160,161,164],{},"先切换到刚创建的 ",[99,162,163],{"code":163},"hermes"," 用户,后续安装、扫码和启动都在同一个家目录完成:",[166,167,173],"pre",{"className":168,"code":170,"language":171,"meta":172},[169],"language-sh","sudo -u hermes -H bash\ncurl -fsSL https:\u002F\u002Fres1.hermesagent.org.cn\u002Finstall.sh | bash\nsource ~\u002F.bashrc\nhermes version && hermes doctor\n","sh","wrap",[99,174,170],{"__ignoreMap":175},"",[14,177,178,179,182,183,186,187,190,191,194,195,198],{},"安装器会把 Hermes 放到 ",[99,180,181],{"code":181},"~\u002F.hermes\u002Fhermes-agent",",命令入口在 ",[99,184,185],{"code":185},"~\u002F.local\u002Fbin\u002Fhermes","。这里的 ",[99,188,189],{"code":189},"~"," 对应 ",[99,192,193],{"code":193},"\u002Fopt\u002Fhermes","。",[99,196,197],{"code":197},"hermes doctor"," 会体检一遍环境,有缺什么它会直接说。",[133,200,202],{"id":201},"_4-装微信适配器依赖","4. 装微信适配器依赖",[14,204,205,206,209,210,213,214,217],{},"依赖必须安装进 ",[48,207,208],{},"Hermes 自己的虚拟环境",",不能用系统 ",[99,211,212],{"code":212},"python3"," 或 ",[99,215,216],{"code":216},"--user","。先解析实际命令位置,再用同一个 venv 的 Python 安装:",[166,219,222],{"className":220,"code":221,"language":171,"meta":175},[169],"HERMES_BIN=\"$(readlink -f \"$(command -v hermes)\")\"\nHERMES_VENV=\"$(dirname \"$HERMES_BIN\")\"\n\"$HERMES_VENV\u002Fpython\" -m pip install aiohttp cryptography qrcode\n",[99,223,221],{"__ignoreMap":175},[133,225,227],{"id":226},"_5-扫码授权","5. 扫码授权",[166,229,232],{"className":230,"code":231,"language":171,"meta":175},[169],"hermes setup --portal\nhermes gateway setup   # 选择 Weixin,按提示扫码\n",[99,233,231],{"__ignoreMap":175},[14,235,236,237,240,241,244,245,247],{},"手机确认登录后,凭据会落在 ",[99,238,239],{"code":239},"~\u002F.hermes\u002Fweixin\u002Faccounts\u002F"," 下,token 写在 ",[99,242,243],{"code":243},"~\u002F.hermes\u002F.env"," 里。此处仍应保持 ",[99,246,163],{"code":163}," 用户身份。启动网关:",[141,249],{"code":250},"hermes gateway",[14,252,253],{},"能持续跑起来、不报缺 token 或依赖错误,就说明链路通了。",[133,255,257],{"id":256},"_6-先上保守策略","6. 先上保守策略",[14,259,260,261,263],{},"刚接通的机器人千万别直接裸奔,我的初始策略写进 ",[99,262,243],{"code":243},":",[166,265,270],{"className":266,"code":268,"language":269,"meta":175},[267],"language-bash","WEIXIN_DM_POLICY=pairing        # 私聊先走配对授权\nWEIXIN_GROUP_POLICY=disabled    # 群消息默认全关\nWEIXIN_ALLOW_ALL_USERS=false\n","bash",[99,271,268],{"__ignoreMap":175},[21,273,276],{"title":274,"type":275},"群消息默认关掉","warning",[14,277,278,279,282,283,194],{},"群策略一旦误开放,群里任何人 @ 一下就能触发机器人。等私聊跑稳、确认好白名单用户 ID 之后,再考虑把私聊切到 ",[99,280,281],{"code":281},"allowlist","、群聊按需开 ",[99,284,281],{"code":281},[133,286,288],{"id":287},"_7-systemd-托管","7. systemd 托管",[14,290,291,292,294,295,263],{},"手动 ",[99,293,250],{"code":250}," 只是验证,常驻还得交给 systemd。写 ",[99,296,297],{"code":297},"\u002Fetc\u002Fsystemd\u002Fsystem\u002Fhermes-gateway.service",[299,300,302],"folding",{"title":301},"hermes-gateway.service 完整配置",[166,303,308],{"className":304,"code":306,"language":307,"meta":175},[305],"language-ini","[Unit]\nDescription=Hermes Agent Gateway\nAfter=network-online.target\nWants=network-online.target\n# 连续启动失败时，5 分钟内最多重试 5 次，避免错误配置无限刷日志。\nStartLimitIntervalSec=300\nStartLimitBurst=5\n\n[Service]\nType=simple\nUser=hermes\nGroup=hermes\nWorkingDirectory=\u002Fopt\u002Fhermes\nEnvironment=HOME=\u002Fopt\u002Fhermes\nEnvironment=PATH=\u002Fopt\u002Fhermes\u002F.local\u002Fbin:\u002Fusr\u002Flocal\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\nExecStart=\u002Fopt\u002Fhermes\u002F.local\u002Fbin\u002Fhermes gateway\nRestart=on-failure\nRestartSec=20\n\n[Install]\nWantedBy=multi-user.target\n","ini",[99,309,306],{"__ignoreMap":175},[166,311,314],{"className":312,"code":313,"language":171,"meta":175},[169],"sudo systemctl daemon-reload\nsudo systemctl enable --now hermes-gateway.service\njournalctl -u hermes-gateway.service -f   # 盯着日志看一会儿\n",[99,315,313],{"__ignoreMap":175},[10,317,318],{"id":318},"踩坑记录",[21,320,323],{"title":321,"type":322},"一个 token 只能一个实例","error",[14,324,325,326,328],{},"同一个微信 token 只允许一个网关实例使用。调试时手动跑了一个 ",[99,327,250],{"code":250},",systemd 那个又在跑,两边互相挤掉线。记住:要么手动要么服务,别同时来。",[330,331,332,349,361],"ul",{},[333,334,335,340,341,344,345,348],"li",{},[48,336,337],{},[99,338,339],{"code":339},"errcode=-14",":会话过期,别慌,停掉服务重新 ",[99,342,343],{"code":343},"hermes gateway setup"," 扫码即可。我后来写了个 ",[99,346,347],{"code":347},"\u002Fusr\u002Flocal\u002Fsbin\u002Fhermes-weixin-login"," 辅助脚本,一键重新出二维码、存凭据、拉起服务。",[333,350,351,263,354,357,358,360],{},[48,352,353],{},"依赖装错环境",[99,355,356],{"code":356},"pip install"," 装到了系统 Python 而不是 Hermes 的 venv,启动直接报缺包,",[99,359,197],{"code":197}," 能查出来。",[333,362,363,366],{},[48,364,365],{},"IPv6-only 的副作用",":微信链路没影响(长轮询出站),但如果以后想让 IPv4-only 的设备访问派上的 Web 面板,得套 Cloudflare \u002F FRP \u002F Tailscale 中转,这是后话。",[10,368,370],{"id":369},"效果在微信里聊两句","效果:在微信里聊两句",[14,372,373],{},"部署完之后,日常画风是这样的:",[375,376,377,380,383,386,389,391,394,396],"chat",{},[14,378,379],{},"{.}",[14,381,382],{},"NAS 还活着吗",[14,384,385],{},"{Hermes}",[14,387,388],{},"✅ NAS-Synology 在线,磁盘占用 62%,温度正常",[14,390,379],{},[14,392,393],{},"树莓派自己呢",[14,395,385],{},[14,397,398],{},"负载 0.42,内存剩余 5.1G,网关已运行 6 天 3 小时",[10,400,401],{"id":401},"后续规划",[14,403,404],{},"机器人接进来只是第一步,和家庭服务管理系统的集成打算分三步走:",[406,407,408,411,414,417,420,423],"timeline",{},[14,409,410],{},"{第一阶段 · 消息入口}",[14,412,413],{},"微信只收管理员私聊命令,命令白名单固定,纯查询:设备状态、服务状态。",[14,415,416],{},"{第二阶段 · 只读运维}",[14,418,419],{},"管理系统提供本机 API,机器人调 API 拿监控摘要、部署任务状态。",[14,421,422],{},"{第三阶段 · 写操作}",[14,424,425],{},"允许微信触发部署\u002F重启,但必须有权限校验、危险操作二次确认和审计日志。",[14,427,428],{},"整体调用边界控制在一条链上:",[166,430,435],{"className":431,"code":433,"language":434,"meta":175},[432],"language-text","Weixin Message -> Hermes Gateway -> Command Parser -> HomeServesManagement API -> Executor -> Audit Log\n","text",[99,436,433],{"__ignoreMap":175},[10,438,439],{"id":439},"结语",[14,441,442],{},"整套方案最让我觉得舒服的点,就是它对网络环境几乎零要求:一块吃灰的树莓派、一个能出网的宽带,微信就变成了家庭运维的入口。没有内网穿透,没有端口映射,没有证书折腾——长轮询在这种场景下是真的香。",[444,445],"link-card",{"description":446,"icon":447,"link":448,"title":449},"部署过程中全程对照的官方文档","https:\u002F\u002Fhermesagent.org.cn\u002Ffavicon.ico","https:\u002F\u002Fhermesagent.org.cn\u002Fdocs\u002Fuser-guide\u002Fmessaging\u002Fweixin","Hermes Weixin 官方文档",{"title":175,"searchDepth":451,"depth":451,"links":452},4,[453,455,456,465,466,467,468],{"id":12,"depth":454,"text":12},3,{"id":54,"depth":454,"text":54},{"id":130,"depth":454,"text":131,"children":457},[458,459,460,461,462,463,464],{"id":135,"depth":451,"text":136},{"id":146,"depth":451,"text":147},{"id":156,"depth":451,"text":157},{"id":201,"depth":451,"text":202},{"id":226,"depth":451,"text":227},{"id":256,"depth":451,"text":257},{"id":287,"depth":451,"text":288},{"id":318,"depth":454,"text":318},{"id":369,"depth":454,"text":370},{"id":401,"depth":454,"text":401},{"id":439,"depth":454,"text":439},[470],"技术","2026-08-02 01:40:00","家里只有 IPv6 公网,没有公网 IPv4,怎么把微信接入自己的运维 Bot?答案是长轮询。记录在树莓派 4B 上部署 Hermes Weixin 网关的完整流程与踩坑。",false,"md","assets\u002Fcover\u002Fcover-weixin-hermes-bot.png",{"slots":477},{},true,"\u002F2026\u002F10004-weixin-hermes-bot",null,{"text":482,"minutes":483,"time":484,"words":485},"7 min read",6.385,383100,1277,50,[488,489],{"title":449,"link":448},{"title":490,"link":491},"Hermes 安装文档","https:\u002F\u002Fhermesagent.org.cn\u002Fdocs\u002Fgetting-started\u002Finstallation",{"title":5,"description":472},{"loc":479},"posts\u002F2026\u002F10004-weixin-hermes-bot",[496,497,498,499,500],"Hermes","微信","树莓派","HomeLab","运维","tech","iUq7mlOuH_Ei7qudyvTvZMv985Yh6xKhkS9tvdf4F9s",[504,509],{"title":505,"path":506,"stem":507,"date":508,"type":501,"children":-1},"Macos终端美化","\u002F2026\u002F10003-terminal_better_macos","posts\u002F2026\u002F10003-Terminal_Better_Macos","2026-05-07 14:51:16",{"title":510,"path":511,"stem":512,"date":513,"type":501,"children":-1},"静态博客零后端评论方案:从 Twikoo 迁移到 Giscus 全记录","\u002F2026\u002F10005-blog-giscus-comment","posts\u002F2026\u002F10005-blog-giscus-comment","2026-08-02 02:30:00",1786956885700]