把AI Agent托管在家用电脑：UU远程终端与端口映射实测记录

为什么会有这个需求

我手上的 AI Agent 大多跑在自己家里的一台小主机上。原因很实际：这些 Agent 经常要调用本地文件、访问局域网里的 NAS、跑一些需要长时间占用的任务，放到云服务器上反而麻烦。但问题也随之而来------我在外面用笔记本或者手机时，想看一下 Agent 跑到哪了、想给它发个新任务，就没办法直接连回去。

家用宽带基本拿不到公网 IPv4，IPv6 又不稳定，路由器改端口转发对很多人来说也不现实。我试过几种方案：内网穿透工具、自己搭 frp、直接 SSH 到一台有公网的跳板机。这次我想试试 UU 远程自带的终端和端口映射能力，看能不能把「远程操作 Agent」和「把 Agent 的 HTTP 接口暴露出去」这两件事一次性解决。

需要先说明：UU 远程本身是网易出的远程控制工具，主要面向游戏和远程桌面场景。它提供的终端、CLI、端口映射这些能力，我是按官方客户端里能看到的入口去用的。如果你用的是其他版本，界面和入口可能不一样，这一点以你本地实际客户端为准。

环境与前置条件

我这边的实际环境是这样的：

项目	配置
被控端（家里）	Windows 11 小主机，16G 内存
主控端（外面）	macOS 笔记本
Python	3.11
Agent 框架	LangChain 0.3.x + 自写的工具调用层
Agent 对外接口	FastAPI + uvicorn

Agent 服务我用 FastAPI 包了一层，这样远程既能通过终端交互，也能通过 HTTP 调。核心思路是：终端负责「操作和调试」，端口映射负责「稳定调用」，两者分工不一样。

先写一个最小可用的 Agent 服务。这里不追求复杂，能跑通、能被远程调用就行：

python 复制代码

# agent_server.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import uvicorn

app = FastAPI(title="home-agent")

class TaskRequest(BaseModel):
    prompt: str

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/run")
def run_task(req: TaskRequest):
    if not req.prompt.strip():
        raise HTTPException(status_code=400, detail="prompt is empty")
    # 这里替换成你真实的 Agent 调用
    result = f"received: {req.prompt}"
    return {"result": result}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

几个点值得说清楚，不是随便写的：

host="0.0.0.0" 是必须的。如果写成 127.0.0.1，只有本机能访问，端口映射出去也没用。
加一个 /health 接口很有必要。远程映射之后，你第一时间想知道的是「服务还活着吗」，而不是「业务逻辑对不对」。
端口我选了 8000，后面端口映射就围绕它来。

装依赖：

bash 复制代码

pip install "fastapi>=0.115" "uvicorn[standard]>=0.30"

版本我写的是下限，因为 FastAPI 和 uvicorn 在这两个大版本之后接口比较稳定。如果和 LangChain 一起装出现依赖冲突，优先保证 LangChain 那条链能跑。

用远程终端先把「能操作」这件事解决

端口映射是给程序用的，终端是给人用的。我的建议是先把终端跑通，因为后面排查端口映射问题，你大概率还是要回到终端上看服务日志。

流程大致是这样：

在家里的被控端装好 UU 远程客户端，登录账号，开启「允许远程控制」。
在笔记本的主控端登录同一个账号，找到这台设备。
进入远程会话后，找到终端入口（不是远程桌面那个画面，是独立的命令行会话）。

这里有个我一开始没注意的点：远程桌面和远程终端是两套东西。远程桌面是画面投屏，适合看 GUI 程序；终端是纯命令行，延迟低、带宽占用小。我一开始一直在远程桌面里开 CMD 敲命令，又卡又难用，后来切到终端入口才顺畅。

进到终端后，第一件事是确认 Python 环境和文件路径：

bash 复制代码

cd C:\agent
python --version
python agent_server.py

服务起来之后，终端里会打印 uvicorn 的启动日志，本地访问 http://127.0.0.1:8000/health 应该返回 {"status":"ok"}。

【踩坑提醒】如果你在远程终端里启动服务，然后把终端窗口关了，服务大概率也跟着挂。Windows 上更稳妥的做法是把它注册成服务，或者用 start /b 之类的方式让它在后台跑。我这次图省事，直接用 pythonw 挂后台，能用但不算优雅：

bash 复制代码

start "" pythonw agent_server.py

这种方式没有日志输出，出问题不好查。如果你要长期托管，建议认真配一个 Windows 服务或者用 nssm 这类工具，别学我。

端口映射：把本机 8000 暴露出去

这是这次最核心的部分。终端解决的是「我能操作」，端口映射解决的是「其他程序/设备能调用」。

在 UU 远程客户端里找到端口映射相关的设置入口，配置逻辑基本都是三段式：

本地地址 / 本地端口：127.0.0.1:8000
映射类型：TCP
远端地址 / 远端端口：客户端分配给你的地址

配好之后，客户端会给你一个类似 xxxx.uu.example:端口号 的地址。注意这里我写的是示意格式，具体分配出来的域名和端口以你客户端实际显示的为准，我没有办法在这里给出一个通用的固定格式。

配好之后验证，分两步走：

第一步，在主控端（笔记本）上用 curl 打一下：

bash 复制代码

curl http://<客户端分配的地址>/health

如果返回 {"status":"ok"}，说明映射链路是通的。

第二步，打一下业务接口：

bash 复制代码

curl -X POST http://<客户端分配的地址>/run \
  -H "Content-Type: application/json" \
  -d '{"prompt":"帮我总结一下今天的待办"}'

两步都通，说明「本机服务 → 端口映射 → 外网访问」这条链路是完整的。

我遇到的问题：映射通了但请求超时

第一次配好之后，/health 能通，但 /run 一直超时。我一开始以为是映射的问题，折腾了半天映射配置，后来发现是 Agent 本身执行太慢------我那个 Agent 会去调本地的大模型，一次要几十秒，客户端默认超时时间不够。

这个坑其实挺好区分：

/health 秒回，/run 超时 → 大概率是业务逻辑慢，不是网络问题。
两个都超时 → 才是映射或网络问题。

所以我在前面强调 /health 接口的价值------它就是你区分「网络层」和「业务层」的分界线。后来我把 Agent 改成了异步任务模式，/run 只负责提交任务返回任务 ID，再开一个 /result/{id} 接口去查结果。这样请求很快返回，不会被超时打断。

【关键结论】端口映射解决的是「能不能连上」，不解决「连上之后业务跑多久」。长时间任务一定要做成异步提交 + 轮询/回调，不要指望一个 HTTP 请求从头等到尾。

网络代理的问题

这里得单独说一段，因为我自己在这上面绕了弯。

家里的那台小主机平时挂着代理，方便访问一些模型 API。但代理一开，本机服务对外暴露时可能出现诡异现象：有的请求走了代理，有的没走，导致端口映射出去的接口时而通时而不通。

我的处理方式是给本机服务加上代理白名单，让对本机地址的访问绕开代理。以常见的环境变量方式为例：

bash 复制代码

set NO_PROXY=127.0.0.1,localhost
set no_proxy=127.0.0.1,localhost

Windows 下这两个变量名大小写都写一遍更保险，因为不同程序读取的变量名大小写不一样。

如果你的 Agent 需要访问外部模型 API，又要被外部访问，就得分清楚：出站的请求走代理，入站的请求走映射。这两条链路是独立的，不要混在一起想。我一开始就没分清，以为是映射的问题，其实是出站代理把请求拦了。

安全这块不能省

把家里的服务暴露到外网，哪怕是走映射，也得有点基本防护。我做了三件事：

加鉴权。最省事的是加一个固定 token：

python 复制代码

from fastapi import Header, HTTPException

API_TOKEN = "换成你自己的随机串"

def check_token(x_token: str = Header(...)):
    if x_token != API_TOKEN:
        raise HTTPException(status_code=401, detail="unauthorized")

然后在接口上挂 Depends(check_token)。

不要暴露管理接口。像重装依赖、执行任意命令这类接口，坚决不要映射出去。
限制 Agent 能碰的文件范围。Agent 调工具的时候很容易越权访问，这个在代码层面限制，别指望网络层。

【注意】token 别硬编码在代码里提交到仓库，用环境变量读。我这里写在代码里只是为了展示写法。

整体跑通之后的效果

最终我的使用方式是：

平时在外面，用远程终端连进去看日志、重启服务、临时调试。
需要程序化调用时，走端口映射的 HTTP 接口，异步提交任务。
长时间任务通过轮询结果接口拿结果。

这套组合跑下来，日常「远程看一眼、临时发个任务」的需求基本满足了。它不是什么高可用方案，但对个人开发者托管自己的 Agent 来说够用。

一些取舍和没验证的部分

有几点我要说清楚，避免误导：

稳定性：这种家用托管方式，遇到家里断电、断网、机器重启，服务就没了。我目前是手动重启，没有做自动拉起。这一点如果要长期跑，得单独解决。
并发：端口映射出去的带宽和并发能力，我没有做过压测，不确定能撑多少并发。个人用没问题，别拿去跑生产流量。
UU 远程端口映射的具体参数 ：不同客户端版本入口和字段名可能不同，我上面写的字段是为了说明配置逻辑，不是让你照抄的固定字段名，以你客户端实际界面为准。
IPv6 场景：如果家里有稳定的公网 IPv6，其实可以直接走 IPv6，不一定需要映射。我这边 IPv6 不稳定，所以没走这条路，这一点我没有深入验证。

如果你也在折腾把本机 Agent 托管出去，我的建议是：先用远程终端把「能操作」跑通，再用端口映射解决「能调用」，最后补上鉴权和异步任务。顺序别反，反了容易在排查问题时分不清是网络问题还是业务问题。

=备用标题=

家用电脑托管 AI Agent 实录：远程终端、端口映射和代理绕行怎么配
没有公网 IP 也能远程调 Agent：我的 UU 远程端口映射实践
把 FastAPI 版 AI Agent 暴露到外网：终端、映射、鉴权一次讲清
AI Agent 托管避坑：远程终端能连但接口超时，问题到底在哪
个人开发者怎么远程管自己的 AI Agent：一套低成本托管思路