前置要求

• 服务器：推荐 Ubuntu 20.04/22.04/24.04 LTS 系统，最低配置 1核2G，推荐 2核4G
• 权限：全程使用 root 用户 或 具备 sudo 权限的用户操作
• 必备：服务器已在「控制台安全组+系统防火墙」开放对应端口，SSH 终端工具（推荐 Xterminal、FinalShell）
• 可选：域名（用于反代与 HTTPS，需提前解析到服务器公网 IP）

1.3 防火墙与端口放行（必做，否则无法访问服务）

1. 安装并启用 UFW 防火墙

sudo apt install ufw -y
sudo ufw enable

2. 放行核心端口（根据你的配置修改）

# SSH 端口（默认22，必放，否则会断开SSH连接）
sudo ufw allow 22/tcp
# 1panel 面板端口（安装时生成，默认随机）
sudo ufw allow 10086/tcp
# NapCat WebUI 端口（自定义，例6099）
sudo ufw allow 6099/tcp
# GSUID Core 核心端口（默认8765）
sudo ufw allow 8765/tcp
# HTTP/HTTPS 端口（反代用）
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

3. 重载生效并验证

sudo ufw reload
sudo ufw status

2.4 NapCat 登录与基础配置

1. 1 【应用商店】→ 【已安装】，确认 NapCat 状态为「已启动」
2. 2 浏览器访问 WebUI：http://你的服务器公网IP:端口/webui?token=你设置的登录密钥
3. 3 扫码/账号密码登录机器人 QQ 号
4. 4 必做基础配置：
   • 【系统配置】→【登录配置】：填写机器人 QQ 号，开启【快速登录】，保存配置
   • 【网络配置】：确认 HTTP 服务开启，记录 HTTP 端口（默认3000，后续 Xwuid 配置用）
   • 【插件商店】：安装【缓存清理】插件，开启自动清理，避免磁盘占用

3.2 安装 uv 高性能 Python 包管理器

uv 替代 pip/venv，大幅提升依赖安装速度，解决依赖冲突问题。

1. 安装 pipx 隔离工具

sudo apt update && sudo apt install -y pipx
pipx ensurepath

2. 关闭当前 SSH 终端，重新连接服务器（让环境变量生效）

3. 安装 uv 与 poetry

pipx install uv
pipx install poetry

4. 备用安装方式（上述失败时使用）

curl -LsSf https://astral.sh/uv/install.sh | sh

5. 验证安装

uv --version

4.4 启动核心框架，验证安装

1. 启动核心程序

uv run core

1. 2 首次启动会自动生成配置文件，无报错、启动成功日志即为安装完成
2. 3 后台运行：Ctrl+C 停止程序，用 Tmux 新建会话重新执行启动命令，Ctrl+b d 分离会话，即可后台常驻运行

6.2 Nginx 反向代理与 HTTPS 配置

6.2.1 安装 Nginx

sudo apt update && sudo apt install -y nginx

6.2.2 配置反向代理

1. 新建站点配置文件（"xwuid.conf"中的xwuid改成自己看得懂的）

sudo nano /etc/nginx/conf.d/xwuid.conf

2. 粘贴以下配置，替换成你的域名与核心端口

server {
    listen 80;
    server_name 你的域名; # 例：xwuid.example.com 或 服务器公网IP

    location / {
        proxy_pass http://localhost:8765;
        # 传递真实客户端信息（必加）
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # 超时配置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
        proxy_buffering on;
    }
}

3. 验证配置并重载生效

sudo nginx -t
sudo systemctl reload nginx

6.2.3 一键配置 HTTPS 证书

1. 安装 Certbot 证书工具

sudo apt update && sudo apt install -y certbot python3-certbot-nginx

2. 一键生成并配置 SSL 证书（替换成你的域名和邮箱）

sudo certbot --nginx -d 你的域名 -m 你的邮箱 --agree-tos --no-eff-email

3. 验证自动续期

sudo certbot renew --dry-run
# 输出 Congratulations 即为自动续期配置成功