以 LLaMA-Factory 端口转发 为核心的实战教程。

---

🦙 LLaMA-Factory 端口转发实战指南

一、为什么需要端口转发？

LLaMA-Factory 启动 Web UI 后，默认输出如下信息：

Visit http://ip:port for Web UI, e.g., http://127.0.0.1:7860 
Running on local URL:  http://0.0.0.0:7860

问题：这个 127.0.0.1:7860 是远程服务器的本地地址，你在自己的电脑上直接访问是打不开的。

解决：通过 SSH 本地端口转发，把远程的 7860 端口"搬"到你电脑的本地端口上。

---

二、转发原理（LLaMA-Factory 场景）

┌─────────────────┐                              ┌─────────────────┐
│     你的电脑     │      SSH 加密隧道              │   远程服务器     │
│                 │  ═══════════════════════════►  │                 │
│  浏览器访问      │                              │  LLaMA-Factory  │
│  localhost:7861 │  ◄═══════════════════════════  │   监听 7860     │
│      ↓          │      数据安全传输               │      ↑          │
│  本地端口 7861   │                              │  远程端口 7860   │
└─────────────────┘                              └─────────────────┘

访问流程：

1. 你在浏览器输入 http://localhost:7861
2. 请求通过 SSH 隧道加密传输到远程服务器
3. 远程服务器把请求转给 LLaMA-Factory 的 7860 端口
4. Web UI 页面原路返回到你的浏览器

---

三、Xshell 配置步骤（详细图解）

步骤 1：定位隧道设置

右键会话名称 → 属性 → 连接 → SSH → 隧道 → 添加

1.左上角点击打开

2.编辑源主机端口（你自己的电脑要接受的端口）和目标端口（服务器需要转发的端口）

步骤 2：填写 LLaMA-Factory 转发规则

配置项	填写值	说明
类型 (方向)	本地 (拨出)	把远程端口映射到本地电脑
源主机	localhost	本地监听地址，保持默认
侦听端口	7861	本地浏览器访问的端口，建议与远程端口区分
目标主机	localhost	指远程服务器本地，保持默认
目标端口	7860	LLaMA-Factory 实际端口，看启动日志确认
说明	llamafactory_webui	自定义备注，方便识别

注意：如果 LLaMA-Factory 启动时显示的是其他端口（如 7862、8080），目标端口要对应修改。

步骤 3：保存并连接

1. 点击 确定 保存规则
2. 点击 连接 建立 SSH 会话
3. 保持 Xshell 窗口在线（隧道随 SSH 连接生效）

---

四、启动 LLaMA-Factory 并访问

4.1 远程服务器启动服务

# 进入 LLaMA-Factory 目录
cd LLaMA-Factory

# 启动 Web UI（以单卡为例）
llamafactory-cli webui

# 或指定参数启动
CUDA_VISIBLE_DEVICES=0 python src/webui.py

看到以下输出表示启动成功：

Running on local URL:  http://0.0.0.0:7860

To create a public link, set `share=True` in `launch()`.

4.2 本地浏览器访问

在你的电脑上打开浏览器，输入：

http://localhost:7861

或

http://127.0.0.1:7861

🎉 成功标志：看到 LLaMA-Factory 的 Web 界面，可以进行模型训练配置了！

---

五、常见场景配置速查

场景 1：标准配置（远程 7860 → 本地 7861）

用途	侦听端口	目标端口	访问地址
LLaMA-Factory Web UI	7861	7860	http://localhost:7861

适用：默认启动，无端口冲突。

---

场景 2：端口被占用（远程 7860 → 本地 8080）

如果本地 7861 被其他程序占用：

配置项	修改值
侦听端口	8080（或其他空闲端口）
目标端口	7860（不变）

访问：http://localhost:8080

---

场景 3：LLaMA-Factory 自定义端口启动

# 远程启动时指定端口为 8080
llamafactory-cli webui --port 8080

对应 Xshell 配置：

配置项	值
侦听端口	8081（本地）
目标端口	8080（远程）

---

场景 4：多实例转发（同时训练多个模型）

实例	远程端口	本地端口	说明
模型 A	7860	7861	第一个 LLaMA-Factory
模型 B	7862	7863	第二个 LLaMA-Factory
模型 C	7864	7865	第三个 LLaMA-Factory

访问方式：

• 模型 A：http://localhost:7861
• 模型 B：http://localhost:7863
• 模型 C：http://localhost:7865

---

六、命令行快速配置（不用 Xshell）

如果你使用终端 SSH，一条命令搞定：

# 格式
ssh -L [本地端口]:localhost:[远程端口] [用户名]@[服务器IP]

# LLaMA-Factory 示例：本地7861 转发到 远程7860
ssh -L 7861:localhost:7860 username@your-server-ip

# 后台运行（不占用终端）
ssh -fN -L 7861:localhost:7860 username@your-server-ip

# 多端口转发（同时转发 TensorBoard 的 6006 端口）
ssh -L 7861:localhost:7860 -L 6007:localhost:6006 username@server

---

七、常见问题排查（LLaMA-Factory 专用）

❌ 浏览器显示 “无法访问此网站”

检查清单：

# 1. 在远程服务器确认 LLaMA-Factory 是否运行
ps aux | grep llamafactory

# 2. 确认端口监听状态
netstat -tlnp | grep 7860
# 或
ss -tlnp | grep 7860

# 预期输出：0.0.0.0:7860 或 127.0.0.1:7860

可能原因	解决方法
SSH 未连接	检查 Xshell 是否已连接服务器
本地端口冲突	更换侦听端口（如 7862、8080）
LLaMA-Factory 未启动	重新执行启动命令
防火墙拦截	确认服务器防火墙放行 7860

---

❌ 页面能打开但显示错误

现象：localhost:7861 能打开，但 LLaMA-Factory 报错或加载失败。

排查：

# 查看远程 LLaMA-Factory 日志
# 通常是 CUDA 错误、模型路径错误等，与端口转发无关

---

❌ 连接一段时间后断开

原因：SSH 空闲超时。

解决：在 Xshell 中设置保持活动状态

属性 → 连接 → 保持活动状态 → 勾选"发送保持活动消息"
间隔设置为 30 秒

---

八、完整工作流程图

┌─────────────────────────────────────────────────────────────┐
│  第 1 步：配置 Xshell 隧道                                    │
│  类型：本地(拨出)  源：localhost:7861  目标：localhost:7860   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  第 2 步：连接 SSH 会话                                       │
│  保持 Xshell 窗口在线，隧道自动生效                            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  第 3 步：远程启动 LLaMA-Factory                              │
│  llamafactory-cli webui                                     │
│  确认输出：Running on local URL: http://0.0.0.0:7860         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  第 4 步：本地浏览器访问                                       │
│  http://localhost:7861                                        │
│  🎉 开始训练你的大模型！                                       │
└─────────────────────────────────────────────────────────────┘

---

九、进阶：同时转发 TensorBoard

训练时需要监控指标，TensorBoard 默认端口 6006：

服务	远程端口	本地端口	说明
LLaMA-Factory	7860	7861	训练配置界面
TensorBoard	6006	6007	训练可视化

Xshell 配置：添加两条转发规则，或一条命令：

ssh -L 7861:localhost:7860 -L 6007:localhost:6006 username@server

访问：

• LLaMA-Factory：http://localhost:7861
• TensorBoard：http://localhost:6007

---

十、总结

配置项	建议值	记忆口诀
类型	本地(拨出)	“从本地出发”
源主机	localhost	固定不变
侦听端口	7861	“本地用 7861”
目标主机	localhost	固定不变
目标端口	7860	“远程是 7860”

核心公式：

浏览器访问：http://localhost:[侦听端口]
                ↓
           SSH 隧道
                ↓
        LLaMA-Factory：http://0.0.0.0:[目标端口]

---

祝你训练顺利！如有其他 LLaMA-Factory 使用问题，欢迎继续交流。