环境说明

• 系统：Ubuntu 26.04（默认 Python 3.14，原生不兼容 QwenPaw 要求的 Python 3.10~3.13）
• 网络：国内网络，无法直连境外服务器，全程使用国内镜像源
• 目标：安装 QwenPaw、配置局域网访问、设置开机自启

---

一、前置说明

1. QwenPaw 官方依赖要求：Python >=3.10 且 <3.14、onnxruntime <1.24，系统自带 Python3.14 存在版本冲突。
2. 不使用系统 Python 环境，采用 Miniconda 独立创建 Python3.11 专属环境，规避版本问题。
3. 最终配置服务监听 0.0.0.0:8088，支持局域网设备访问，并配置系统用户级开机自启。

---

二、步骤1：安装 Miniconda（国内镜像）

1. 下载并安装 Miniconda

# 下载国内镜像版 Miniconda
wget https://mirrors.bfsu.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 静默安装
bash Miniconda3-latest-Linux-x86_64.sh -b

# 激活 conda 环境
source ~/miniconda3/bin/activate

2. 接受仓库服务条款（Ubuntu26 新版 Conda 必做）

conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

---

三、步骤2：创建 Python3.11 专属环境

Python3.11 完全适配 QwenPaw 版本要求：

# 创建名为 qwenpaw 的环境，指定 Python3.11
conda create -n qwenpaw python=3.11 -y

# 进入环境
conda activate qwenpaw

---

四、步骤3：安装 QwenPaw（国内清华源）

# 升级 pip
pip install -U pip

# 安装 QwenPaw（自动拉取全部依赖）
pip install qwenpaw

基础命令验证

执行以下命令，输出帮助信息即代表安装成功：

qwenpaw --help

首次初始化

qwenpaw init --defaults

---

五、步骤4：配置系统自启服务（监听 8088 端口，支持局域网）

1. 创建 systemd 用户服务文件

# 创建用户级服务目录
mkdir -p ~/.config/systemd/user/

# 编辑服务配置文件
nano ~/.config/systemd/user/qwenpaw.service

2. 写入服务配置内容

复制以下完整配置粘贴到文件中：

[Unit]
Description=QwenPaw Service
After=network.target

[Service]
# 监听所有网卡 0.0.0.0，端口固定 8088，局域网可访问
ExecStart=/home/can/miniconda3/envs/qwenpaw/bin/qwenpaw app --host 0.0.0.0 --port 8088
WorkingDirectory=/home/can
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

说明：

• --host 0.0.0.0：允许局域网所有 IP 访问，仅写 127.0.0.1 则只能本机访问
• --port 8088：固定服务端口

3. 保存并退出编辑器

按 Ctrl+O 保存 → 回车 → 按 Ctrl+X 退出。

4. 启用并启动自启服务

# 重载 systemd 配置
systemctl --user daemon-reload

# 设置开机自启
systemctl --user enable qwenpaw

# 立即启动服务
systemctl --user start qwenpaw

5. 查看服务运行状态

systemctl --user status qwenpaw

出现 active (running) 表示服务正常运行。

---

六、步骤5：防火墙放行 8088 端口（局域网访问必备）

Ubuntu 默认使用 ufw 防火墙，放行端口：

# 放行 8088 端口（所有局域网设备均可访问）
sudo ufw allow 8088/tcp

# 重载防火墙规则
sudo ufw reload

# 查看防火墙状态
sudo ufw status

安全加固（可选，仅允许同网段访问，示例网段 192.168.1.0/24）：

sudo ufw allow from 192.168.1.0/24 to any port 8088 proto tcp

---

七、步骤6：验证访问 & 端口监听

1. 检查端口监听状态

ss -tuln | grep 8088

正常输出示例：

LISTEN  0      4096          0.0.0.0:8088        0.0.0.0:*

2. 获取本机局域网 IP

hostname -I

示例输出：192.168.1.105

3. 访问地址

• 本机访问：http://127.0.0.1:8088
• 局域网其他设备访问：http://你的局域网IP:8088

---

八、常见问题排查

问题1：提示 [Errno 98] address already in use 端口被占用

杀掉占用 8088 端口的进程，再重启服务：

kill -9 $(lsof -t -i:8088) 2>/dev/null
systemctl --user restart qwenpaw

问题2：局域网无法访问

1. 检查防火墙：sudo ufw status，确认 8088 端口已放行
2. 检查服务监听地址：确认是 0.0.0.0:8088 而非 127.0.0.1:8088
3. 确认设备处于同一局域网，无网段隔离

问题3：手动启停服务命令

# 停止服务
systemctl --user stop qwenpaw

# 重启服务
systemctl --user restart qwenpaw

# 取消开机自启
systemctl --user disable qwenpaw

---

九、环境使用补充

1. 手动进入 Conda 环境（临时手动运行命令）

   source ~/miniconda3/bin/activate
   conda activate qwenpaw
   

2. 卸载相关（如需）
   • 停止并禁用服务：systemctl --user stop qwenpaw && systemctl --user disable qwenpaw
   • 删除服务文件：rm ~/.config/systemd/user/qwenpaw.service
   • 删除 Conda 环境：conda remove -n qwenpaw --all -y