注意！本指南为进阶指南
请确保你之前已经独立完成过分离部署 NapCat 或者 LLBot，并了解其中每项设置的含义。本指南不再讲解基础概念！
—
💡常见问题 (FAQ)
Q：为什么不用 WSL2 反而用 WSL1？
A：虽然 WSL2 性能更好……但是动态ip，每次重启服务器都要搞更多的端口转发，很麻烦的！WSL1 就完全没有这个负担，直接 127.0.0.1 就解决了！而且 WSL1 没有 Linux 内核，也没有虚拟机，像是一个翻译层，所以不需要为操作系统本身预留内存。它的内存开销几乎等同于在 Windows 上直接运行一个普通的 .exe 程序，内存占用极低。
Q：为什么不直接在 Windows 上分离部署 NapCat / LLBot？
A：Linux 版本的 QQ 协议目前风控更少、更稳定！相比 Windows 版，公认的更稳！
Q：为什么不用 Docker？
A：我也很想用……可是我鼓捣了好久发现我的 Windows Server 2019 服务器始终装不上 Linux Docker，所以才选择使用 WSL 的
Q：这么费劲，我为什么不直接选择 Linux 服务器？
A：OlivOS 其实更适合 Windows 服务器部署，很多 GUI 界面 Linux 服务器是看不到的
适用环境：Windows Server 2019 及以上 (或 Win10/11)
—
📋 目录
- 环境准备：开启 WSL 功能
- 系统安装：安装 Ubuntu
- 环境配置：Linux 基础依赖安装
- NapCat部署：NapCat 安装与配置 (WSL 端)
- 兼容桥接：部署 Python 路径修复代理 (Windows 端)
- OlivOS连接：OlivOS 配置与启动
- 持久化：开机自启设置（可选）
—
一：开启 WSL 功能 (Windows 端)
在 Windows Server 上，必须先手动开启子系统功能并重启。
- 以 管理员模式 打开 PowerShell。
- 运行以下命令让 Windows Server 允许运行 Linux 子系统：
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
- 运行以下命令开启虚拟机平台功能（增强兼容性）：
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
- ⚠️ 必须重启服务器 才能生效。
—
二：安装 Ubuntu 系统 (离线/在线方案)
方法一：一键安装指令 (仅限 Server 2022 或 Win10 2004+)
如果使用的是 Windows Server 2022、Win10 (2004+) 或 Win11，且网络能连上微软服务器——那么就直接用这个吧
- 管理员模式打开 PowerShell。
- 输入：
wsl --install -d Ubuntu-20.04
- 如果进度条走完并提示重启，那么直接可以跳到第三步！
- 如果报错或无反应（Server 2019 常态），请使用下面的方法二。
方法二：使用应用商店抓取站离线安装 (推荐)
首先嘛……如果你能稳定连接微软服务，那么可以使用官方直链下载：https://aka.ms/wslubuntu2004
很显然，几十几百kb去下载那900m……猴年马月！那么使用第三方吧！
（其实这个第三方也很慢……但是比微软直链还是快很多倍的！）
（而且，微软直链我挂梯子是50-100kb/s，这个第三方我挂梯子能飚到10+mb/s！）
1. 下载链接
- 直接在服务器上（或者网速快的电脑上）打开这个网站网站：https://store.rg-adguard.net/
- 输入参数：
- 第一个下拉框：URL (link)
- 中间输入框：
https://www.microsoft.com/store/productId/9n6svws3rx71 (Ubuntu 20.04 地址)
- 右边下拉框：Retail（当然 RP 也行）
- 点击右侧的勾勾
2. 下载目标文件
列表加载后，找到符合以下特征的文件下载：
- 文件名：包含
CanonicalGroupLimited...Ubuntu...20.04...x64，我这里显示的是CanonicalGroupLimited.Ubuntu20.04onWindows_2004.2022.8.0_neutral_~_79rhkp1fndgsc.appxbundle
- 后缀：通常是
.appxbundle
- 大小：900MB - 1GB 左右
3. 套娃解压安装
由于下载的是 Bundle 包，里面包含多种 CPU 架构的文件，我们需要剥离出 x64 版本。
第一层解压：
- 将后缀名从
.appxbundle 改为 .zip。
- 右键解压。
寻找核心包：
- 进入解压后的文件夹，找到一个文件名包含
x64 且后缀为 .appx 的文件。
- 注意：这个文件大小通常在 400MB - 500MB 左右。不要选 ARM 的，也不要选几 KB 的 blockmap。
第二层解压：
- 将这个
.appx 文件的后缀名也改为 .zip。
- 如果还没上传服务器的话，这时候就可以将这个核心包上传服务器了
- 再次右键解压这个新压缩包。
转移路径：
- 这个文件夹就是你的 WSL 子系统所在文件夹！所以一定要转移到一个合适的位置！
- 我就将这个文件夹转移到了
E:\Ubuntu
运行：
- 进入最后一次解压的文件夹。
- 找到
ubuntu2004.exe
- 双击运行。
- 黑框弹出提示
Installing...，稍等片刻后设置 Username (用户名) 和 Password (密码) 即完成安装。
- 注意：因为 Linux 的特性，你入密码时屏幕上是什么都不会显示的（没有星号，光标不动），这是正常的！ 凭自己的感觉输完就行！
—
三：Linux 环境基础配置 (WSL 端)
进入 Ubuntu 黑框（WSL 终端）。
注意：使用sudo命令时要输入密码！
1. 换源 (可选，如果下载慢)
sudo sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list
sudo sed -i 's/security.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list
2. 安装必要依赖
一次性安装 NapCat 和后续步骤需要的工具：
sudo apt update
sudo apt install -y curl wget screen git python3 python3-pip libgbm-dev libasound2 unzip
—
四：部署 NapCat (WSL 端)
1. 一键安装
curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && sudo bash napcat.sh
2. 进行基础配置
填写对应的 HTTP 上报地址和 HTTP 服务，此处不再进行赘述。因为使用的是 WSL1，子系统和主机共用一个 IP 地址，所以进入 NapCat 的 WebUI 直接在外面的 Windows 上打开浏览器输入 127.0.0.1:6099 就行！
⚠️注意！
这里的 HTTP 端口号一定不能和你 OlivOS 里面的端口号相同！具体下面一步会讲，要做端口转发！
—
五：部署 Windows 路径修复代理 (Windows 端)
如果你是在外面的 Windows 搭建的 OlivOS，那么发送的文件路径是 Windows 格式 (E:\xxx)，WSL 里的 NapCat 无法识别，发不出来图片，语音等，所以我们需要一个 Python 脚本在中间做翻译。
1. 安装 Python
在 Windows Server 上下载安装 Python 3，安装时一定要勾选 “Add Python to PATH”。
（当然你也可以在 WSL 里面完成，哪边都行）
2. 安装依赖
打开 CMD 运行：
pip install flask requests
3. 创建端口转发脚本
注意这里以OlivOS 端口为 10149，NapCat 端口为 10150为例子
在 Windows 任意位置（如 C:\NapCatTools\）或者在你的 WSL 子系统里新建 proxy.py，丢入以下进行端口转发：
import sys
import os
import re
import logging
import json
from flask import Flask, request, jsonify
import requests
# ================= 配置区 =================
LISTEN_PORT = 10149 # 脚本监听端口 (给 OlivOS 连)
NAPCAT_URL = "http://127.0.0.1:10150" # NapCat 地址 (WSL 端口)
# =========================================
app = Flask(__name__)
# 禁用 Flask 默认的烦人日志
log = logging.getLogger('werkzeug')
log.setLevel(logging.ERROR)
print("==========================================")
print("[SYSTEM] Proxy Started Successfully")
print(f"[LISTEN] Local Port: {LISTEN_PORT}")
print(f"[TARGET] Forward To: {NAPCAT_URL}")
print("[MODE] Detailed Logs & Smart Path Fix")
print("==========================================\n")
def convert_path_to_wsl(text):
"""
智能转换函数：
只转换真正的 Windows 路径，忽略 URL 协议头 (如 file://, http://)
"""
if not isinstance(text, str):
return text
# 正则表达式详解：
# (?<![a-zA-Z]) -> [前瞻] 前面不能紧跟字母 (防止把 file: 误判为盘符)
# ([a-zA-Z]): -> [捕获] 盘符 (Group 1)
# (?!//) -> [后顾] 后面不能紧跟两个斜杠 (排除 http://, file:// 等协议)
# ( -> [捕获] 路径部分 (Group 2)
# [\\/] -> 必须以斜杠开头 (\ 或 /)
# [^,\]\"<>\s]+ -> 贪婪匹配直到遇到分隔符
# )
pattern = r'(?<![a-zA-Z])([a-zA-Z]):(?!//)([\\/][^,\]\"<>\s]+)'
def replace_callback(match):
drive = match.group(1).lower()
# 把 Windows 的反斜杠 \ 统一换成正斜杠 /
path_rest = match.group(2).replace('\\', '/')
# 拼接成 WSL 路径: /mnt/e/folder/file.jpg
new_path = f'/mnt/{drive}{path_rest}'
print(f"[FIX] Path Converted:\n Source: {match.group(0)}\n Target: {new_path}")
return new_path
# 简单预判：只有包含冒号和斜杠的字符串才尝试正则，节省性能
if ':' in text and ('\\' in text or '/' in text):
return re.sub(pattern, replace_callback, text)
return text
def fix_json_recursive(data):
"""递归遍历 JSON 树，无死角清洗所有字符串"""
if isinstance(data, dict):
for k, v in data.items():
if isinstance(v, str):
data[k] = convert_path_to_wsl(v)
else:
fix_json_recursive(v)
elif isinstance(data, list):
for i, item in enumerate(data):
if isinstance(item, str):
data[i] = convert_path_to_wsl(item)
else:
fix_json_recursive(item)
@app.route('/', defaults={'path': ''}, methods=['POST', 'GET'])
@app.route('/<path:path>', methods=['POST', 'GET'])
def proxy(path):
print(f"\n[RECV] Incoming Request: /{path}")
try:
# 1. 获取数据
params = request.args.to_dict() # URL 参数 (Token 等)
json_data = request.json # Body 数据 (消息内容)
# === 详细日志打印 ===
if params:
print(f"[DEBUG] URL Parameters: {params}")
if json_data:
# 格式化打印接收到的原始数据
try:
print("[DEBUG] Raw JSON Payload:")
print(json.dumps(json_data, ensure_ascii=False, indent=2))
except:
print("[DEBUG] Raw JSON Payload: (Print Failed)")
# ==================
# 2. 执行路径修复
if json_data:
fix_json_recursive(json_data)
# 3. 转发给 NapCat
target_url = f"{NAPCAT_URL}/{path}"
resp = requests.request(
method=request.method,
url=target_url,
params=params,
json=json_data, # 这里的 json_data 已经是修复过的了
headers={k:v for k,v in request.headers.items() if k.lower() != 'host'}
)
# 4. 打印转发结果
if resp.status_code == 200:
print(f"[FWD] Forwarded to NapCat -> OK (200)")
else:
print(f"[FWD] Forwarded to NapCat -> FAILED ({resp.status_code})")
print(f"[RESP] NapCat Response: {resp.content.decode('utf-8', errors='ignore')}")
return (resp.content, resp.status_code, resp.headers.items())
except Exception as e:
print(f"[ERROR] Proxy Exception: {e}")
return jsonify({"status": "failed", "msg": str(e)}), 500
if __name__ == '__main__':
app.run(host='127.0.0.1', port=LISTEN_PORT)
4. 运行测试
此处以 Windows 上为例
- 新建一个
start_proxy.bat
python proxy.py
pause
双击 start_proxy.bat，保持黑框开启。
—
六：配置 OlivOS (Windows 端)
进行正常配置即可，注意端口一定要填写正确！（本指南例：10149）
启动连接。
- 发送指令
- 观察上面的转发脚本 CMD 黑框是否有日志
- 观察 QQ 里面是否成功发出来
- 继续尝试发送图片，确认日志显示
[FIX] E:\... -> /mnt/e/...，并且能正常接收到图片
—
七：设置开机自启（注意！这里纯是AI给的，我只是略做修改，并没有测试过，仅供参考！）
1. 自启 Python 代理
之前的start_proxy.bat创建一个快捷方式
2. 自启 WSL NapCat
新建 StartNapCat.bat：
@echo off
wsl screen -dmS napcat bash -c "cd /home/你的用户名/NapCat && ./napcat.sh -q 你的QQ号; exec bash"
(注意替换上面的“你的用户名”和“你的QQ号”)
创造一个快捷方式
3. 加入启动项
- 按
Win + R，输入 shell:startup。
- 将上面的
start_proxy.bat 和 StartNapCat.bat 文件的快捷方式拖入该文件夹。
—
🎉 到这里就部署完成了！具体还有任何疑问可以留言交流！
碎碎念：大晚上用手机鼓捣了 4 个小时.jpg，真的要感谢 AI，感谢哈基米的大力指导啊.jpg
