本地模型在局域网下被其他设备访问的配置教程

本地部署大语言模型的价值不止于"自己这一台机器能用"。把部署在 GPU 主机上的模型服务开放到局域网后，家里的笔记本、平板、手机，或者办公室里没有显卡的同事电脑，都能共享同一份模型与同一块显卡，避免每个人都重复下载几十 GB 的模型文件。本教程是《llama.cpp本地部署Qwen3.8大语言模型完整教程》的续作，在其部署完成的本地服务基础上，讲解局域网访问的核心原理（监听地址与防火墙）、a4agent 图形界面一键开放、llama-server 命令行手动开放、多设备客户端调用与安全加固的完整过程。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• llama.cpp本地部署Qwen3.8大语言模型完整教程，本教程的直接前置，在其部署完成的本地模型服务之上开放局域网访问。
• OpenAI兼容API的概念与用法详解，局域网设备调用的正是 llama-server 暴露的 OpenAI 兼容 API，概念完全一致。
• Ollama本地部署大语言模型完整教程，Ollama 默认同样只监听本机，其 OLLAMA_HOST 环境变量的思路可与本教程相互印证。

资源下载

• a4agent v0.2.1 Release 发布页（Gitee），本教程使用 v0.2.1 及以上版本的 Lite 安装包，内置引擎按显卡自动下载与一键局域网开放。
• llama.cpp 官方 GitHub Releases 发布页，手动部署原版 llama.cpp 的高级用户参考，命令行做法对原版完全适用。

1. 原理：服务为什么"别人连不上"

1.1 监听地址：127.0.0.1 与 0.0.0.0

每一台电脑都有一块"回环网卡"（Loopback），对应的地址是 127.0.0.1，它只代表"本机自己"。一个网络服务启动时必须选择绑定到哪个地址上：

llama-server 默认监听 127.0.0.1，这就是部署完成后"本机能用、其他设备连不上"的根本原因。开放局域网访问的本质只有两步：把监听地址改为 0.0.0.0，再在防火墙为它放行入站端口。

1.2 第二道门：Windows 防火墙

改了监听地址只是让服务"愿意接听"，数据包要真正进入主机，还必须通过 Windows 防火墙这一关。防火墙对入站连接的默认策略是阻止，因此即使服务已经监听 0.0.0.0，只要没有放行规则，其他设备依然连接超时。

这里有一个新手极易踩中的坑：当服务第一次监听端口时，Windows 会弹出"是否允许访问网络"的对话框，如果随手点了取消，系统会自动创建一条阻止规则，而且此后不再弹窗——于是一直连不上，也很难想到原因。Windows 防火墙中"阻止规则"的优先级高于"允许规则"，必须删除阻止规则、新增允许规则才能修复，本教程第 4 章给出完整命令。

1.3 找到 GPU 主机的局域网 IP

其他设备要访问，得知道往哪个地址访问。在 GPU 主机打开 PowerShell 执行：

ipconfig

在输出中找到当前使用的网卡（无线局域网适配器 WLAN 或以太网适配器以太网）下的 IPv4 地址，形如 192.168.3.29。两点提醒：

• 127.0.0.1 不是局域网 IP，它只代表本机。
• 机器上装有 WSL、Docker、虚拟机软件时，会多出 172.17.x.x、172.2x.x.x 等虚拟网卡地址，这些地址只有本机能访问，不要把它们发给其他设备的用户。判断方法很简单：虚拟网卡的地址一般没有网关，而真实网卡的网关（默认网关一行，通常是 192.168.3.1 这类）与它是同网段的。

2. 方式一：a4agent 图形界面一键开放

a4agent v0.2.1 及以上版本已将本教程的全部配置收敛为界面上的一个开关，推荐新手使用。

2.1 勾选局域网访问开关

打开 a4agent 控制台，切换到「设置」页，找到「局域网访问」一行，勾选「允许局域网设备访问」：

点击「保存设置」。若服务正在运行，需要「停止」后再「启动」使新监听地址生效，日志页出现 [就绪] health ok 字样即代表服务就绪。

2.2 从接入页获取局域网地址

切换到「接入」页，勾选开关后，页面中的局域网提示会自动给出其他设备可访问的完整地址：

已允许局域网访问：其他设备可改用 http://192.168.3.29:8080/v1

a4agent 会自动跳过 WSL、Hyper-V 等虚拟网卡，只显示真实物理网卡的地址；接入页同时提供 Base URL、Chat Completions 完整地址、模型名称与可一键复制的 curl、Python 调用示例，发给局域网内的其他用户即可直接使用。

2.3 首次启动的防火墙弹窗

开放局域网后的第一次启动，Windows 会弹出"Windows 安全中心警报"对话框：

• 勾选「专用网络」（家庭与办公室可信网络），点击「允许访问」即可。
• 误点了「取消」也不必重装，按第 4.3 节的命令删除自动生成的阻止规则即可恢复。

3. 方式二：命令行手动开放（原版 llama.cpp 适用）

不使用 a4agent、直接使用原版 llama.cpp 的用户，只需在启动命令中追加 --host 参数。原版 llama-server 的默认监听地址同样是 127.0.0.1：

# 仅本机可访问（默认行为）
llama-server.exe -m Qwen3.8-27B-Q4_K_M.gguf --port 8080

# 局域网可访问：显式指定监听地址
llama-server.exe -m Qwen3.8-27B-Q4_K_M.gguf --host 0.0.0.0 --port 8080

启动后日志首行会打印监听地址，看到 main: server is listening on http://0.0.0.0:8080 即代表开放成功。--host 0.0.0.0 表示在所有网卡上监听，也可以写成具体局域网 IP（如 --host 192.168.3.29）实现精确绑定。

原版用户还需自行完成第 4 章的防火墙放行，两个方式只差一个图形界面，网络原理完全一致。

Ollama 用户的等价操作是设置环境变量 OLLAMA_HOST=0.0.0.0 后重启 ollama serve，监听原理与端口放行方式与本教程完全相同。

4. 防火墙放行详解

4.1 验证服务监听状态

在 GPU 主机执行以下命令，确认服务已经监听在 0.0.0.0 上：

netstat -ano | findstr :8080

输出中 LISTENING 前一列是监听地址，应为 0.0.0.0:8080；若显示 127.0.0.1:8080，说明监听地址尚未修改，回到第 2 章或第 3 章处理。

4.2 在本机先用局域网 IP 自测

curl http://127.0.0.1:8080/health
curl http://192.168.3.29:8080/health

两条命令都应返回 {"status":"ok"}。第二条通过真实网卡自测，可以提前排除"监听地址没改对"这类本机问题，把问题域收窄到防火墙。

4.3 查看与修正防火墙规则

以管理员身份打开 PowerShell（开始菜单搜索 PowerShell，右键"以管理员身份运行"），先查看 llama-server 相关的现有规则：

Get-NetFirewallApplicationFilter -Program '*llama-server*' | Get-NetFirewallRule |
    Select-Object DisplayName, Direction, Action, Enabled, Profile

健康的状态应当只有 Action=Allow 的入站允许规则。如果看到 Action=Block 的规则（弹窗点取消产生的），删除它们并新增允许规则：

# 删除所有 llama-server 相关的旧规则（含误创建的阻止规则）
Get-NetFirewallApplicationFilter -Program '*llama-server*' |
    Get-NetFirewallRule | Remove-NetFirewallRule

# 按程序路径放行（路径替换为你的 engine 目录）
New-NetFirewallRule -DisplayName 'llama-server (a4agent allow)' `
    -Direction Inbound -Action Allow `
    -Program 'C:\Users\你的用户名\AppData\Local\Programs\a4agent-Lite\engine\llama-server.exe' `
    -Profile Any

# 或者按端口放行（对任意位置的 llama-server 均生效，粒度更粗）
New-NetFirewallRule -DisplayName 'llama-server port 8080' `
    -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow -Profile Any

-Profile Any 表示对"专用网络"和"公用网络"都生效。家庭路由器下的网络一般是专用网络；若只想在可信的家用网络开放，可将 -Profile Any 改为 -Profile Private，并将该网络的网络配置文件属性设置为"专用"。

完成后再执行一次第 4.2 节的自测，然后就可以在其他设备上验证了。

5. 局域网设备的客户端调用

以下命令均在局域网内的其他设备上执行，地址中的 192.168.3.29 替换为你 GPU 主机的局域网 IP。

5.1 浏览器与 curl

llama-server 自带 WebUI，手机或平板的浏览器直接访问即可对话：

http://192.168.3.29:8080/

命令行设备用 curl 验证连通性并完成一次对话：

# 健康检查
curl http://192.168.3.29:8080/health

# 对话补全
curl http://192.168.3.29:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen3.8-27B-Uncensored-Q4_K_M", "messages": [{"role": "user", "content": "用一句话介绍你自己"}]}'

5.2 Python openai SDK

在局域网内任意一台装了 Python 的设备上：

from openai import OpenAI

client = OpenAI(base_url="http://192.168.3.29:8080/v1", api_key="none")

resp = client.chat.completions.create(
    model="Qwen3.8-27B-Uncensored-Q4_K_M",
    messages=[{"role": "user", "content": "写一句今天的工作计划"}],
)
print(resp.choices[0].message.content)

与调用云端 API 唯一的区别就是 base_url 指向局域网地址，模型名换成本地 GGUF 的文件名（不含 .gguf 后缀）。

5.3 第三方客户端

Cherry Studio、ChatBox、NextChat 等支持自定义 OpenAI 接口的图形客户端，配置方法一致：服务商类型选 OpenAI 或"自定义"，API 地址填 http://192.168.3.29:8080/v1，API Key 随意填写，模型名手动输入本地模型文件名。

6. 安全注意事项

开放局域网访问等于把无鉴权的推理服务暴露给同一网络内的所有设备，请按需加固：

llama-server 未配置 --api-key 时不校验任何凭证，局域网内任何人都可以消耗你的显存与电费。家庭可信网络可以接受，公司网络强烈建议启用密钥。另外，本教程的全部配置仅限于局域网使用；若确有公网访问需求，请使用带鉴权的反向代理（如 Nginx + HTTPS + Basic Auth）而非直接端口映射。

7. 连接失败排查清单

其他设备连不上时，按顺序逐项检查，绝大多数问题都能在前三步定位：

其中第 5 步常被忽略：部分路由器的"访客网络"或"AP 隔离"功能会禁止局域网设备互相访问，现象是能 ping 通网关但设备之间完全不通，需要在路由器管理后台关闭。

8. 总结

8.1 核心内容回顾

• 局域网访问的本质是两步：监听地址改为 0.0.0.0，防火墙放行入站端口；任何"连不上"的问题都逃不出这两步加网络可达性。
• a4agent 用户在设置页勾选「允许局域网设备访问」并重启服务，接入页会自动给出正确的局域网地址与调用示例。
• 原版 llama.cpp 用户在启动命令追加 --host 0.0.0.0，效果完全相同。
• 防火墙弹窗点取消会生成阻止规则，且阻止规则优先于允许规则；排查时先用 Get-NetFirewallApplicationFilter 查看现有规则。
• 找 GPU 主机的 IP 时注意跳过 WSL、Docker 等虚拟网卡地址，真实网卡的特征是与默认网关同网段。
• 局域网开放后服务无鉴权，半可信网络务必追加 --api-key，并永远不要将端口直接映射到公网。

8.2 常见问题与解答

问：其他设备能 ping 通主机，但 8080 端口连不上？

答：ping 通只说明网络可达，端口被防火墙拦截是另一回事。按第 4.3 节检查是否存在 Action=Block 的入站规则，删除后新增允许规则即可。

问：接入页显示的局域网地址是 172 开头的，手机连不上？

答：这是 WSL 或 Hyper-V 虚拟网卡的地址，仅本机可达。a4agent v0.2.1 起会自动过滤虚拟网卡并显示真实物理网卡地址，请升级到 v0.2.1 及以上版本；也可以自行用 ipconfig 找与默认网关同网段的 IPv4 地址。

问：手机用流量可以访问，连 WiFi 反而不行？

答：流量访问的是公网，说明服务被映射到了公网，存在严重安全风险，请立即删除路由器上的端口映射规则。连 WiFi 不通则是本教程要解决的问题，按第 7 章清单排查，重点检查 AP 隔离。

问：局域网内多人同时调用，会互相排队吗？

答：会。llama-server 默认单路并发，第二个请求需要等第一个完成。可以在 a4agent 设置页调大「并行槽位」（对应 --parallel 参数），或调小上下文长度为并发腾出 KV cache 显存；多路并发会摊薄每个请求的可用算力，速度相应下降。

问：设置了 --api-key 之后客户端报 401？

答：客户端 api_key 字段必须填写与启动参数完全一致的密钥值；使用浏览器 WebUI 时，在页面右上角的 API Key 设置中填入同一密钥即可。

问：改了监听地址或防火墙，需要重启电脑吗？

答：都不需要。监听地址修改后重启 a4agent 服务即可生效；防火墙规则保存后立即生效，无需任何重启。