Linux QQ Bot 部署从入门到入土——以 Debian12 为例

本文所述内容仅作为技术分享，作者不鼓励、不提倡、不支持任何使用本文内容进行违法违规活动的行为；使用相关技术进行的违法违规活动与作者无关。

为了方便零基础的读者理解，本文中部分定义进行了简化，如果你想要学习更专业的表达和用法，请自行查找相关资料。

因为不理解本文内容盲目按照本文操作造成损失的情况，作者概不负责。

前言

之前暑假期间在家里搞了一台升腾 C92 的小主机，刷了 Linux 后用来部署 QQ Bot，实际使用效果不错，便把自己原本在云服务器上跑的几个无需公网 ip 的服务迁移到了小主机上。最近又有不少群友来询问我搭建 QQ Bot 相关的问题。于是我准备整理一下从安装到部署的全过程供大家参考。

本文假设读者有最基本的计算机常识，能够正确理解编辑文件、压缩和解压，能够使用 Windows 或 macOS 完成一般的日常工作。

本文中绝大部分演示操作将使用命令行而非图形界面或面板。如果需要图形化教程请自行寻找相关文档。

预备知识

这一节中我们将总结一些关于 Linux、协议、网络安全等领域常见的问题。这一部分建议所有读者阅读。如果你非常赶时间或者已经有一定基础知识，可以先跳过这一部分，等需要时再回来阅读。

Linux 及其发行版

GNU/Linux 操作系统，通常简称 Linux 操作系统，是一系列基于 GNU 软件和 Linux 内核的操作系统的统称。Linux 和 macOS 一样以 Unix 操作系统为原型，因此有极其稳定、安全的特点（我要点名表扬某个会自动更新然后蓝屏的操作系统了），并且由于核心部分完全开源免费，在服务器上有着大量的应用。

同时由于 Linux 只要遵守相关开源协议就可以被自由修改、分发，各种在此基础上修改后的版本也层出不穷，这些版本被称为不同的发行版，其中较为出名的有 Ubuntu、Fedora、UOS等。不同发行版之间虽然大体相似，但是各自的使用方式又有着很大的不同。因此选择适合自己实际需求的发行版是很重要的。

在本文中，我们将使用 Debian 这一发行版，其中大部分操作对于基于 Debian 的数十种主流发行版（如 Ubuntu、Mint 等）都适用。这里选择 Debian 主要基于其简单稳定、适合新手入门，同时又较为轻量的特点，你也可以根据你的需求使用其他发行版。

桌面环境（DE）与电传打字机（tty）

tty 就是 Linux 里的「纯文字界面」—— 屏幕只有黑底白字，没有图标、没有窗口，想让电脑干活只能用键盘敲命令（比如输 ls 看文件），就像早期没有鼠标的老式电脑，这也是本文里我们和小主机交互的主要方式。

而 Windows 和 macOS 的「桌面环境（DE）」，就是我们平时用的「图形界面」—— 能看到桌面图标、能拖放窗口、能用鼠标点 “此电脑”（Windows）或底部程序坞（macOS），靠点一点、拖一拖就能操作电脑，不用记命令。

两者的关系很简单：它们都是 “人指挥电脑的工具”，只是操作方式不一样。就像叫外卖，tty 是 “手动输手机号下单”（敲命令），Windows/macOS 的 DE 是 “点屏幕上的商家头像下单”（图形操作），最终目的都是让电脑完成任务，但形式完全不同。

需要特别说的是：不是有图形的 DE 就更高级。尤其在小主机、服务器上，tty 反而更实用 —— 它占用的内存、CPU 特别少，能省出资源给 QQ Bot 这类核心服务；而且熟练后敲命令比点鼠标快得多，并且可以使用他人为我们准备好的自动化脚本，一条命令能顶反复点鼠标几十次。事实上后面我们在 NapCat 和 MaiBot 的安装过程中，就能够体会到这种方式的便捷。

用户与权限

很多日常使用 Windows 或 macOS 的同学，对用户和权限概念的理解非常模糊。为了方便大家理解，这里我将用最简单的语言帮助读者了解用户与权限的相关规则。

对于一般的读者来说，在 Linux 中有两种用户：普通用户和 root 用户（也称为超级管理员）。每个用户都有一个自己的目录，被称为 home 目录，也称家目录，在终端中常常用 ~ 来表示。对于普通用户来说，家目录位于 /home/用户名 的位置；对于 root 用户来说，家目录位于 /root 的位置。一般情况下，普通用户只能够对自己家目录下的文件进行修改。为了实现这一点，Linux 有一套权限管理机制。

用ls -l命令查看文件时，会看到类似这样的信息：

-rwxr-xr-- 1 user group 114514 Sep 11 07:21 file.txt

开头的-rwxr-xr--就是权限：
- 第 1 位-：表示是文件（d表示目录）。
- 2-4 位rwx：文件所有者（Owner） 有读、写、执行权限（能随意操作这个文件）。
- 5-7 位r-x：同组用户（Group） 有读和执行权限（能看、能运行，但不能改）。
- 8-10 位r--：其他用户（Others） 只有读权限（只能看，不能改也不能运行）。

简单来说，Linux 的用户和权限就是通过「给人分组、给文件设规则」，确保系统里的每个资源都被「合适的人」以「合适的方式」使用，既灵活又安全。

我们来举个例子：可以把 Linux 系统理解为一个合租公寓，用户和权限机制就是管理公寓入住和房间使用规则的体系，核心可以简单总结为：「谁（用户）可以对什么东西（文件 / 目录）做什么操作（读 / 写 / 执行）」。

用户与用户组

Linux 中每一个操作必须由某个用户发起，就像公寓里面每件事都必须要由某个租客来完成。

超级管理员（root）相当于「房东」，拥有整个公寓（系统）的最高权限，可以随意进入任何房间（访问文件和目录）、修改任何规则（修改访问规则和所有权）、添置公寓设备（安装软件），甚至赶走其他租户（删除用户），拆掉整个公寓（删除系统）。

普通用户相当于「租客」，只能在自己的房间（家目录）自由活动，对公共区域（如 /usr、/etc等目录）的操作会受到限制。

同时，为了方便资源的管理，Linux 还有用户组（Group）的概念。

用户组相当于一个「合租室友群」，可以让一个组群中的用户同时享有某些权限。把多个用户加入同一个组，就可以方便地管理他们的共同权限，比如让室友们都能使用客厅的饮水机（某个文件）。

权限

每个文件 / 目录都有 3 组固定权限，对应「文件所有者（Owner）、同组用户（Group）、其他用户（Others）」三类人，每组权限包含「读（r）、写（w）、执行（x）」三种操作，像房间门上的三把锁。

读（r，数字 4）：可以查看内容，比如打开房间门看一眼里面有什么。
写（w，数字 2）：可以修改内容，比如在房间里摆放家具或扔掉东西。
执行（x，数字 1）：可以运行 / 进入，比如执行一个程序（像启动房间里的洗衣机）或进入一个目录（像走进房间，但无读权限时，即使能进入也看不到里面的文件）。

有时候我们常常遇到 Permission denied 这样的提示就是因为文件权限不足，这个时候我们一般有两种解决方案：第一种方法是修改文件或目录的权限，让我们可以直接进行操作，这种一般用于从网络下载的默认不允许执行的软件中；第二种方法则是「请」拥有相关权限的用户，通常是超级管理员，来帮我们完成操作，这一过程被称为提权，在实际使用中，我们常常使用 sudo 软件来帮助我们完成这一操作。

绝对路径与相对路径

我们要对某个文件或目录进行操作时，需要通过某种方式来定位目标的位置，这个时候就需要用到路径（Path）来表示文件或者目录的位置了。路径通常分为绝对路径和相对路径两种。

绝对路径是从系统根节点开始的：在 Windows 中，以盘符为根节点，不同目录的层级关系使用反斜杠（\）表示，如 C:\；在 Linux 和 macOS 中，以统一的根目录（/）为唯一根节点，不同目录的层级关系使用斜杠（/）表示，如 /home/Cecelia/Documents。

使用绝对路径的好处是我们可以从系统最底层开始找，只要文件还在系统里，我们总能够顺藤摸瓜找到这个文件所在的位置。但是同时其问题也非常明显：如果我的文件所在的目录层数很深的时候，每次我们都要完整地输入一遍绝对路径，这显然是非常麻烦且不优雅的。聪明的人们想到，我能不能先让我位于某个目录的位置，然后从这个位置出发，去查找这个目标文件或目录呢？于是我们就有了另一种表示路径的方式：使用工作目录和相对路径来表示目标文件的位置。

在相对路径中，我们使用 . 来表示工作目录，即“当前所处的位置”；使用 .. 来表示上一级目录。用这种方法我们就可以在较深的目录中使用简短的路径。同时相对路径开头的 ./ （Windows 中为 .\）往往可以省略不写。例如我的工作目录为 /home/Cecelia/Documents 时，想要分别访问 Cecelia 目录下的 Music 文件夹和 Documents 目录下的 Lolita.txt 时，我们可以用下面路径查找：

# Music 文件夹
/home/Cecelia/Music # 绝对路径
../Music # 相对路径
# 圣经.txt
/home/Cecelia/Documents/Lolita.txt # 绝对路径
./Lolita.txt # 相对路径

这样对比下来，我们就能很明显感受到相对路径的简单了。

不过相对路径对于工作目录的依赖性较高，并且访问浅层目录时可能比绝对路径更加繁琐，有些时候我们仍然需要使用绝对路径。

Linux 常用软件和命令

我是很不提倡去死记硬背这种东西的，实际上用多了就会发现常用的软件和命令就只有那么一些，下面我们就来介绍一些常用的软件和命令。

列出文件 ls

这应该是大多数 Linux 新手会接触到的第一个指令。ls 的作用很简单，它会列出当前目录下的所有文件。同时可以配合其他参数使用，具体的参数感兴趣的读者可以自行查询，通常我们使用 ls -al 即可，这个指令会列出所有当前目录下文件和文件夹的同时展示文件的大小、所有者、修改时间、权限等常用信息。

打印工作目录 pwd

这也是常用的一个命令，它的作用是在终端打印输出当前工作目录。

切换工作目录 cd

这个命令的作用是切换当前工作目录，支持绝对路径和相对路径。输入 cd 目标目录 即可。

编辑文本 nano

nano 是 Debian 操作系统默认的命令行 TUI （TUI 指文本用户界面，区别于图形用户界面 GUI）文本编辑器，使用 nano 文件路径 即可打开文件。相比于 vi 或者 vim 等编辑器更加适合新手使用。操作总体上和 GUI 下的编辑器相同，使用上下左右方向键移动光标，使用下方的命令进行复制、粘贴、保存、退出等操作。

如果你想要使用 vim ，请自行查找相关教程，本文不作介绍。

移动 / 重命名 mv

这个命令的作用是用于移动和重命名文件或文件夹。使用 mv 旧文件路径新文件路径 的格式使用，也支持绝对路径和相对路径，可以同时实现文件移动和重命名。

复制 cp

这个命令的作用是复制文件，如果需要复制文件夹，需要添加 -r 参数。其他用法和 mv 完全一致。

新建文件夹 mkdir

这个命令的作用是新建文件夹，在后面加上要创建的文件夹的路径即可。

以管理员身份 sudo

这个命令的意义是加载其他命令前，然后使用 root 用户的身份运行这条命令。除非你明确遇到了权限问题，否则不应该使用 sudo 来执行操作，尤其是删除等高危险操作。

需要注意的是使用 sudo 后，在路径中出现的 ~ 会被解析为 root 用户的家目录 /root。

删除 rm

rm 命令的作用是删除文件。使用此命令删除的文件是不可恢复的！使用此命令删除的文件是不可恢复的！使用此命令删除的文件是不可恢复的！重要的事情说三遍。

如果你要删除文件夹，和 cp 一样请使用 -r 参数。

删除操作是极其危险的，如果你不知道你在做什么，不要使用 root 用户身份执行 rm 命令！使用此命令删除的文件是不可恢复的！

包管理器（APT）

在Linux中很多应用程序并不能单独运行，他们可能需要使用其他应用的功能来完成一些自己的功能，举一个最简单的例子，如果你希望安装一个图形化的软件，那么你大概率需要先安装qt、gtk或者其他类似的图形平台来让软件能够实现图像化。与Windows和MacOS上通常将软件本体及其所有依赖打包为一个单独的软件不同，在Linux上几乎所有软件（这里我们不讨论flatpak和Appimage等打包格式）都必须依赖于系统中的其他软件，这样做的好处是很明显的，假如两个软件A、B都依赖相同的软件C，我们就只需要安装一遍C就可以实现同时使用A、B和C三个软件，大大节省了磁盘空间。

但是这样做的坏处也很明显，我每次安装软件都需要去额外处理大量的依赖，这显然是非常巨量的工作。这时，聪明的你发现，如果有一个程序能够自动读取和处理软件的依赖列表，和当前系统中已有的软件包进行对比，自动补充缺少的软件包，不就解决这个问题了吗。于是，能够自动处理软件安装依赖的工具就诞生了，你给这破玩意儿起名叫做包管理器。

和日常用的电脑不同，Linux 操作系统很多时候不能使用 Windows、Android 上使用安装包、或者 MacOS 上直接拖动复制安装的方式进行，而是需要借助名为包管理器来实现软件安装，在 Debian 以及其他基于 Debian 的操作系统上，包管理工具为 apt，这一工具我们会在之后安装软件时多次使用。

由于包管理器需要对于整个系统的公共文件进行修改，因此需要使用 root 用户权限运行，通常我们在运行时都需要搭配 sudo 软件使用。

这里列出一些常见的 apt 指令：

1. 系统更新（前置必做）

指令	功能说明	示例
`sudo apt update`	更新本地包索引，获取远程仓库软件最新版本信息（仅更新列表，不升级软件）	`sudo apt update`
`sudo apt upgrade`	升级已安装软件（需手动确认，不删除旧包，不处理复杂依赖冲突）	`sudo apt upgrade`
`sudo apt full-upgrade`	升级软件并自动处理依赖变化（可能删除不兼容旧包，适合跨版本升级）	`sudo apt full-upgrade`

2. 软件安装

指令	功能说明	示例
`sudo apt install [软件名]`	安装指定单个软件	`sudo apt install firefox`（安装火狐浏览器）
`sudo apt install [软件1] [软件2]`	同时安装多个软件	`sudo apt install git vim`（安装 Git 和 Vim）
`sudo apt install [软件名]=[版本号]`	安装软件指定版本（需先通过 `apt show` 确认可用版本）	`sudo apt install python3=3.8.10-0ubuntu1~20.04.7`

3. 软件卸载

指令	功能说明	示例
`sudo apt remove [软件名]`	删除软件，保留配置文件（重新安装可沿用旧配置）	`sudo apt remove chrome`
`sudo apt purge [软件名]`	彻底删除软件及所有相关配置文件（无残留）	`sudo apt purge chrome`

4. 软件查询

指令	功能说明	示例
`apt list --installed`	列出系统所有已安装软件（可搭配 `grep` 筛选）	`apt list --installed \| grep python`（筛选已安装的 Python 相关包）
`apt show [软件名]`	查看软件详细信息（版本、依赖、安装大小、描述等）	`apt show ubuntu-desktop`
`apt search [关键词]`	在远程仓库搜索含关键词的软件	`apt search video player`（搜索视频播放器）
`apt policy [软件名]`	查看软件的安装来源和可用版本	`apt policy nginx`

5. 系统清理

指令	功能说明	示例
`sudo apt autoremove`	自动删除“无软件依赖”的无用包（如残留的临时依赖）	`sudo apt autoremove`
`sudo apt clean`	清理本地包缓存（删除 `/var/cache/apt/archives/` 下所有 `.deb` 安装包）	`sudo apt clean`
`sudo apt autoclean`	清理本地包缓存（仅删除远程仓库已不存在的旧版本 `.deb` 文件）	`sudo apt autoclean`

6. 问题修复

指令	功能说明	示例
`sudo apt -f install`	修复因依赖损坏导致的安装/升级失败（自动补装缺失依赖）	`sudo apt -f install`

网络安全

这一部分主要是针对使用服务器或者有公网的用户。请使用服务器的用户务必认真阅读本节内容。

IP 地址

IP地址是服务器在网络中的“门牌号”，分为公网IP和内网IP，两者在安全属性上差异显著。

核心概念区分

内网IP：仅在局域网内可访问（如服务器所在机房、家庭路由器下的192.168.x.x、10.x.x.x），默认不暴露在公网，安全性较高。

公网IP：可被互联网中任意设备访问（如服务器绑定的独立IP），是服务器与外界交互的入口，也是安全防护的核心靶点。

安全注意事项

避免“裸奔”暴露：不要将服务器的公网IP随意分享至公开平台（如论坛、社交软件），防止被恶意扫描工具抓取。
警惕异常访问：定期通过服务器日志（如Linux的/var/log/auth.log）查看IP访问记录，若发现陌生IP频繁尝试登录（如SSH连接），需及时拦截。
优选固定公网IP：若使用云服务器，建议选择固定公网IP而非动态IP，方便后续绑定防火墙规则、域名解析，减少IP变动带来的安全配置遗漏。

防火墙

防火墙是服务器的“守门人”，通过预设规则控制进出服务器的网络流量，默认拒绝所有非必要访问，是公网服务器的第一道安全屏障。

目前主流Linux发行版（如Debian、Ubuntu 20.04+）默认使用ufw（简单防火墙），操作简单适合新手；部分系统也支持iptables（功能更强大但配置较复杂），这里重点介绍ufw的基础用法。
核心实操配置（以 ufw 为例）

基础状态控制
- 启用防火墙：sudo ufw enable（启用后重启服务器仍生效，需确保已配置必要端口，避免自己无法登录）。
- 查看状态与规则：sudo ufw status verbose（可查看当前允许/拒绝的端口、IP等规则）。
- 关闭防火墙（紧急情况用）：sudo ufw disable。
关键端口配置（遵循“最小必要原则”）
- 允许SSH端口（远程登录必备，默认22端口，若修改过端口需替换）：sudo ufw allow 22/tcp（仅允许TCP协议，减少UDP协议的攻击面）。
- 允许Web服务端口（如搭建海豹需开放3211端口）：sudo ufw allow 3211/tcp。
- 拒绝特定IP：若发现某IP恶意访问，可直接拦截：sudo ufw deny from 192.168.1.100（将IP替换为实际恶意IP）。
安全原则
- 不开放无用端口：如服务器不提供FTP服务，就不要开放 21 端口；不开放 3001（NapCat ws 服务器默认端口）给公网，可限制仅允许特定内网IP连接。
- 定期检查规则：若服务器功能调整（如停用Napcat Web服务），需及时删除对应端口规则：sudo ufw delete allow 6099/tcp。

对于使用阿里云等平台，需通过云控制台配置防火墙的用户，请自行参考服务商的文档设置安全组，注意事项同上。

实际上，对于有时间学习的用户，若仅需基础远程登录与 Web 服务，建议只开放 22 端口、80 端口和 443 端口，并合理使用 nginx、caddy 等反向代理来提高安全性。具体操作请自行查找文档，此处不做介绍。

鉴权与 Token

鉴权是验证“访问者身份是否合法”的过程，Token（令牌）是常用的鉴权方式之一，尤其适用于API接口、Web服务等场景，比传统“账号密码”更灵活安全。

鉴权的本质是“验证身份”，比如服务器判断登录的用户是否有操作某个文件的权限、某个API请求是否来自合法客户端。

Token是一段加密的字符串，由服务器（Napcat ws 服务器，MaiBot ws 方向协议，海豹核心与NapCat Web UI）生成或配置，客户端（如海豹 ws onebot 正向协议、NapCat ws 客户端、浏览器）获取Token后，后续访问时携带Token，服务器通过验证Token的有效性来确认身份。

对于使用服务器、有公网 IP 或使用内网穿透的用户来说，Token（密码）是必须配置的。2025年初以来的多次攻击事件已经给了我们很多血淋淋的教训：未配置 Token 的服务极易成为攻击目标，珍爱 Bot，好好设置 Token。

关于 SSH：服务器厂商通常已预设安全策略，小主机用户通常无需开放公网 SSH，同时考虑到此内容对于新手来说较为难以理解，此处暂不展开，有余力的读者请自行查找相关文档学习。

系统安装与基础配置

这一部分中我们将要完成 Debian12 系统的安装。如果你是服务器用户，请直接在镜像中选择 Debian
12.x （任意 12 版本）后前往下一部分进行阅读。

为了方便截图提高大家的阅读体验，安装过程我将使用虚拟机进行演示。针对实体机安装遇到的部分问题，我将单独说明。

在正式安装前，确保你有以下设备或软件：

一台可以工作的电脑
一个不少于 8 GB 的 U 盘或移动硬盘
一台准备安装 Linux 的小主机
一个供小主机使用的键盘
一台供小主机使用的显示器
可以让小主机访问互联网的网络环境
Debian12 系统安装媒介（iso文件）

准备安装引导程序与安装镜像

我们需要一个大小不少于8G且没有重要数据的U盘（U盘在制作启动盘时会被格式化，切记提前备份数据！）用来存放系统镜像，常用的这类工具有不少，这里我们以 Ventoy 为例。

用这种方法的好处是在安装后如果出现系统级的崩溃和错误，连 tty 都无法进入时可以用安装镜像修复系统错误或者抢救数据。并且 Ventoy 在一次准备后可以存放多个系统镜像，把 Windows 安装媒介和 PE 都放进去，实在是居家旅行必备良品（雾）。

Ventoy 的具体使用方法参考官网教程或者网上其他文档，没有什么难度，这里不过多介绍。

系统安装

假如说你在安装过程中遇到了类似「找不到安装镜像挂载点」之类的报错，大概率是因为你使用了没有分区且未被格式化的硬盘。这种情况下请使用 PE 或者其他设备格式化该硬盘，之后应该就能正常工作了。

0.启动安装程序

将准备好的 Debian 安装媒介文件拷入准备好的 Ventoy 盘中，插入小主机上，启动电源。大概会看到下面的界面，部分 cpu 机器可能会是 TUI 界面，但是内容应该相同。

选择准备好的的 Debian 镜像，然后回车。

选择「以正常模式启动」，继续回车。如果你因为某些原因这里失败了，使用第二项「使用 grub2 启动」。接下来进入安装页面。

选择第二项「安装」，使用 TUI 安装。个人认为图形化安装并不好用，如果你非要尝试也可以使用。操作是几乎一样的。

1.语言与时区

选择 English，大部分设备选择中文会出现满屏幕⬜的「口口相传」现象。输入回车确认操作。

接下来选择地区，依次选择 other/Asia/China。

然后字符编码和键盘映射都使用默认的美国即可，改为中文会口口相传。

2.网络配置

接下来如果你插好了网线，系统会自动为你分配好你的网络设置。如果你使用 Wi-Fi 连接，提前把家中 Wi-Fi 名称改为英文的，然后按照提示输入 Wi-Fi 名称和密码连接即可。

网络连接这一步根据你的网络情况可能需要十几秒到几分钟，请耐心等待。

然后进入主机名和域名的配置

首先是配置主机名，一般默认的系统名即可，你也可以改一个自己喜欢的名字。

然后是域名，使用 localhost 即可。

3.设置用户

设置并确认 root 密码，这个密码必须记住！这个密码必须记住！这个密码必须记住！如果丢失是很难找回或重置的。

接下来设置普通用户，输入你的用户名，这里建议全名和用户名都使用纯小写字母组成的短名字，这里我起名为 syy。然后是同样的设置并确认密码，为了安全，这里请和 root 用户使用不同的密码。

4.设置时钟

这一步通常系统会自动完成。

5.磁盘分区

接下来我们要格式化磁盘并进行分区。我们选择「使用一整块硬盘并设置 LVM」。

选择小主机自己的磁盘，也就是不是 U 盘那一块。

分卷这里使用推荐的默认选项即可。

确认所选磁盘正确后选择 Yes 和 Continue 格式化并挂载磁盘。

然后完成分区并应用到目标磁盘，选择 Yes 确认。

6.安装系统

安装程序会自动安装基础系统。过程中会询问我们是否使用网络镜像，我们选择 Yes。

选择使用的网络镜像源，这里我们选择 China，如果你在其他地区，选择你所在的地区即可。

选择中科大镜像源（mirrors.ustc.edu.cn），如果速度较慢可以多试几个，选择速度最快的。

接下来设置代理，一般留空即可。

接下来就是漫长的等待 apt 更新，这个过程视你的网络质量需要几十秒到几分钟。

然后安装程序要询问我们要不要帮助 debian 的镜像变得更好，这里选 Yes 或 No 都可以。

然后接下来安装程序会让我们勾选需要的软件。这里按 空格 取消勾选前两项桌面环境，如果你需要使用 ssh 可以勾选，如果你不知道 ssh 是什么，只勾选最后一项即可。完成后回车。

接下来等待安装完成，视你的网络情况需要几分钟或者几十分钟。

这个过程中提示我们安装引导程序界面，选择小主机的系统盘，不要选择 U 盘。

耐心等待安装完成后。选择 Continue 重启电脑，这个时候可以拔出你的 U 盘。

完成安装

重启电脑后，应该可以看到下面的 gurb 引导界面。按下回车进入系统。

进入登陆页面，输入你的用户名，回车后输入密码，注意这里输入密码后不会显示，直接回车确认即可。

出现下面的输出表明登陆成功，可以开始使用了。

安装基本软件工具

接下来我们安装一些常用的软件，首先我们需要以 root 身份登入来安装 sudo。

su - # 登入 root 用户

# 这里输入密码时同样不会有任何显示，输入完直接回车即可。

# 安装 sudo
apt install sudo

# 将你的用户加入 sudo 组，这里 syy 需要修改为你自己的用户名
usermod -aG sudo syy

接下来重新登入普通用户，安装其他软件。

# 登入用户
su syy # 这里 syy 替换为你的用户名

在执行 sudo 的时候会提示我们输入密码，注意这时需要输入当前用户的密码而非 root 用户的密码。

首先我们要修改 apt 的镜像源，使用网络镜像源而非安装镜像中的软件源。

sudo nano /etc/apt/sources.list

删除第一行的内容即可，然后依次按下 Ctrl + X 、 Y 、回车 保存并退出。

然后更新软件源。

sudo apt update

安装中文字体和控制台配置工具，让 tty 能够显示中文。

sudo apt install fonts-wqy-zenhei zhcon

配置系统 Locale 为 UTF-8。

sudo dpkg-reconfigure locales

找到其中的 zh_CN.UTF-8 按下Tab 选中。

然后选择 zh_CN.UTF-8 回车确认。

接下来启动 zhcon。

zhcon --utf8

接下来 tty 应该就可以正常显示中文了。

安装 curl、wget 和 git 用于从网络下载文件。

sudo apt install curl wget git

获取内网 ip 地址

之后我们使用很多地方需要使用 web UI 来进行配置，因此需要获取内网 IP 地址。

使用 ip a 命令查看本机网络配置。

这里红线部分就是内网 ip 地址，将这个地址记住，后面我们配置 web UI 时会用到。

协议端部署

安装 NapCat

这一部分我们简单介绍 NapCat 的安装和使用配置。这一部分参考了 NapCat 官方文档内容

在小主机中输入下面的命令安装 NapCat ：

curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& bash napcat.sh \

第一项直接回车，第二项输入 y 后回车（这里图是错的，不用管它）。然后输入你的密码。

耐心等待自动安装程序完成 NapCat 的安装。

然后使用 napcat help 查看文档。

NapCat 启动与网络配置

接下来使用 napcat start {QQ} 启动 NapCat。然后使用 napcat log {QQ} 查看。

找到这里生成的 token ，然后打开浏览器，输入 ip:6099 访问 web UI。输入刚才的 token 并登陆。如果你是服务器用户，请前往防火墙或安全组放行 6099 端口的入方向。

在登陆页面选择二维码登陆，并扫码登陆 QQ 账号。

登陆后就进入了 web UI 管理页面。

接下来讲解如何配置代理。不管是 ws 协议还是 http 协议，不管是正向还是反向，配置都是大同小异的，下面我们以 ws 服务器（正向协议）说明如何创建网络配置。

点击左侧 网络配置/新建/Websocket服务器。

到这里 NapCat 的配置就完成了，去 Bot 应用端连接到协议端即可。

海豹核心部署

海豹核心在 Linux 上的部署及其简单。下面我们演示一遍完整的部署流程。

下载与解压海豹核心

首先我们在家目录下创建一个文件夹用于存放海豹。

cd ～
mkdir sealdice
cd sealdice

然后访问海豹官网，找到适宜自己架构的安装包（一般为x86），然后右键选择复制连接。

在终端输入复制的地址，用 wget 下载文件。

wget https://d1.sealdice.com/sealdice-core_1.5.1_linux_amd64.tar.gz

使用 tar 解压文件。

tar -xzf ./sealdice-core_1.5.1_linux_amd64.tar.gz
ls

使用 chmod 为海豹添加可执行权限

chmod +x ./sealdice-core

海豹就已经安装好了。

启动海豹核心

接下来我们为海豹添加自启动服务。

sudo ./sealdice-core -i

如果没有报错，那么海豹核心就已经开始工作了。打开浏览器，输入 ip:3211 访问 web UI。输入刚才的 token 并登陆。如果你是服务器用户，请前往防火墙或安全组放行 3211 端口的入方向。

如果你使用公网服务器，请第一时间按照引导设置一个 web UI 访问密码。

接下来介绍一下海豹如何连接分类部署的 NapCat 协议端。

首先确保你已经参考之前的设置配置好了 NapCat 的 ws 正向服务器。

在海豹 web UI 的账号管理处添加一个账号。

这里显示为已连接即为连接成功。

其他操作和 Windows 上完全一致，不做过多讲解。

补充：关于文件管理

这里可能就有同学要问了。我如果骰子搬家，我之前的 data 文件夹怎么挂上去呢？

诶，这个时候就需要我们万能的 NapCat 大人出场了。是的，NapCat 大人自带了一个文件管理面板，我们直接拖动上传即可。

请大家把「NapCat 牛逼！」打在公屏上。

顺便再回答一下「Linux 上如何解压 zip 格式文件」的问题。我们需要安装一个 unzip 软件来解压。

sudo apt update
sudo apt install unzip

然后使用 unzip data.zip 解压即可。

好了，到此为止关于海豹的常见问题应该就都解决了。

MaiBot 部署

接下来是 MaiBot 的部署，这里我们还是按照官方文档的步骤来安装。本文只介绍基础安装流程，配置、插件等内容请自行查阅官方文档。

预备知识（python）

在这里我们要补充讲解一些关于 uv 和 python 的知识。还是老规矩，建议所有读者阅读。如果你非常赶时间或者已经有一定基础知识，可以先跳过这一部分，等需要时再回来阅读。

先把两个核心概念掰扯清楚：

下文中，Python（大写） 若无特殊说明，单指 Python 编程语言 —— 就像 “中文”“英文” 是交流的语言规则，Python 是写代码的 “语法规则”，而且只聊 Python 3 及以上版本（老版本早就没人用了，不用管）。

python（小写） 则特指 Python 解释器 —— 它是一个实际的软件，作用类似 “翻译机”：你用 Python 语法写的代码（比如让 Bot 发消息、处理群聊的指令），电脑本身看不懂，需要 python 解释器逐行读、逐行解析，再转成电脑能执行的操作。没有它，写好的 Python 代码就是一堆没用的文字。

包管理

写代码时，没人会从零开始 “造轮子”。比如想让 Bot 发网络请求（调用 AI 接口）、存配置（像 Token、群号），甚至处理群消息里的表情符号，这些常用功能早有人写好了现成的代码，打包成 “工具集” 供人直接用 —— 这些 “工具集” 就是 Python 包。

简单说，Python 包就是 “别人做好的代码轮子”。

在 Python 程序开发和运行时，我们常常需要调用第三方包，而很多包之间也存在和 Linux 软件包类似的依赖关系（看不懂的话，可以回头看前文包管理器的介绍）。于是人们专门开发了针对 Python 第三方包的包管理器，pip 就是最典型的一个。

接下来，你的一切工作似乎的非常顺利，直到……

依赖冲突

某一天，你运行 Python 程序时发现第三方包 C 用不了，检查后发现：它依赖包 D 的一个旧版本接口，但你系统里的其他包大多只需要 D 的新旧版本都有的接口。这就造成了 依赖冲突。

为了解决这个问题，你在依赖说明里添上符合要求的版本，把所有依赖 D 的包的需求取个交集 —— 比如算出来 1.14 版本的 D 刚好满足所有需求，于是用 Python 包管理器把 D 的版本改成了 1.14。

不可调和的依赖冲突与依赖污染

你开始把开发依赖存到单独的文件夹里，和系统自带的依赖（base 环境）彻底分开，两者互不干扰；同时，给每个项目配一份单独的依赖环境。这样一来，上面的问题全解决了 —— 人们把这个方法叫做 虚拟环境。

从此，虚拟环境配合包管理器，再也不用担心依赖冲突了，可喜可贺～

虚拟环境

你开始把开发时需要的依赖存放在一个单独的文件夹中与系统依赖（base 环境）彻底分开，这样两者就不会产生冲突，同时，针对不同的项目，你可以为每一个项目配置一份单独的依赖环境，彻底解决了上面的问题，你管这个新的发明叫做虚拟环境。

从此，通过虚拟环境与包管理器的配合，你和服务器过上了幸福的生活，真是可喜可贺，可喜可贺……

uv

现在你已经了解了包管理、虚拟环境的基本概念，接下来介绍 uv。

uv 是一个 Python 包管理工具，同时具备 Python 版本管理、包管理、虚拟环境管理等功能，比 Python 官方工具更简单、更可靠。

接下来，我们就用 uv 配置 Python 环境，让 MaiBot 顺利在设备上跑起来。

安装并配置 MaiBot 及其 NapCat 适配器

首先我们需要安装 uv。使用 uv 官方提供的安装脚本安装 uv。

curl -LsSf https://astral.sh/uv/install.sh | sh
source ～/.local/bin/env

现在 uv 就被正确安装了。

接下来我们使用 uv 安装 python3.12 版本——这是 MaiBot 官方推荐的版本。

由于 Python 的一些问题，有时候使用最新版本的 Python 反而容易产生一些问题，如果你没有排查错误的能力，这里使用旧版本即可。

uv python install 3.12

然后我们下载 MaiBot 的代码到本地。

cd ~
mkdir ./maimai
cd ./maimai
git clone https://github.com/MaiM-with-u/MaiBot.git
git clone https://github.com/MaiM-with-u/MaiBot-Napcat-Adapter.git

安装依赖

首先为 MaiBot 核心创建虚拟环境并安装依赖。

uv venv --python 3.12
cd MaiBot
uv pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple --upgrade
# 创建文件夹
mkdir config
# 复制并重命名配置文件
cp template/bot_config_template.toml config/bot_config.toml
cp template/model_config_template.toml config/model_config.toml
cp template/template.env .env

接下来为 NapCat 适配器创建虚拟环境并安装依赖，同时启用配置文件。

cd ../MaiBot-Napcat-Adapter
uv pip install -i https://mirrors.aliyun.com/pypi/simple -r requirements.txt --upgrade
# 复制并重命名文件
cp template/template_config.toml config.toml

最终文件结构应该如图：

maimai
├── .venv # 虚拟环境
├── MaiBot # MaiBot 核心
│&nbsp;&nbsp; ├── changelogs
│&nbsp;&nbsp; ├── config
│&nbsp;&nbsp; ├── data
│&nbsp;&nbsp; ├── depends-data
│&nbsp;&nbsp; ├── src
│&nbsp;&nbsp; │&nbsp;&nbsp; └── ...
│&nbsp;&nbsp; └── template
└── MaiBot-Napcat-Adapter # MaiBot NapCat 适配器
    ├── config.toml
    └── template

配置 NapCat

这里 NapCat 的配置方法已经在前文讲述此处不再赘述。

启动

之后的启动流程参考官方文档的内容。

补充：编写自动化运行脚本

这里我们每次都输入一大堆指令显得非常麻烦，这里我为了偷懒编写了两份快速启动的脚本，贴出来供大家参考。

使用本脚本前请先安装一些依赖：

sudo apt update
sudo apt install tmux

然后编写下面两个文件：

maibot.sh：

#!/bin/bash

# 定义会话名称
SESSION_NAME="maibot"
# 定义执行命令的目录
EXECUTION_DIR="${HOME}/maimai"
# 定义要执行的命令
COMMAND=".venv/bin/activate && cd \"${EXECUTION_DIR}/MaiBot\" && uv run python3 bot.py"

# 检查执行目录是否存在
if [ ! -d "$EXECUTION_DIR" ]; then
    echo "错误：执行目录 $EXECUTION_DIR 不存在！"
    exit 1
fi

# 检查会话是否已经存在
if ! tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
    # 会话不存在，创建新会话并在指定目录下运行命令（cd失败则退出）
    tmux new-session -d -s "$SESSION_NAME" \
        "cd \"$EXECUTION_DIR\" && $COMMAND || read -p '命令执行失败，按任意键退出...'"
    echo "会话 $SESSION_NAME 创建成功。"
else
    # 会话已存在，提示信息
    echo "会话 $SESSION_NAME 已存在，正在连接..."
fi

# 连接到会话
tmux attach -t "$SESSION_NAME"

adapter.sh：

#!/bin/bash

# 定义会话名称
SESSION_NAME="maibot"
# 定义执行命令的目录（展开~为绝对路径，避免tmux环境中路径解析问题）
EXECUTION_DIR="${HOME}/maimai"
# 定义要执行的命令（使用绝对路径更可靠）
COMMAND=".venv/bin/activate && cd \"${EXECUTION_DIR}/MaiBot-Napcat-Adapter\" && uv run python3 main.py"

# 检查执行目录是否存在
if [ ! -d "$EXECUTION_DIR" ]; then
    echo "错误：执行目录 $EXECUTION_DIR 不存在！"
    exit 1
fi

# 检查会话是否已经存在
if ! tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
    # 会话不存在，创建新会话并在指定目录下运行命令（cd失败则退出）
    tmux new-session -d -s "$SESSION_NAME" \
        "cd \"$EXECUTION_DIR\" && $COMMAND || read -p '命令执行失败，按任意键退出...'"
    echo "会话 $SESSION_NAME 创建成功。"
else
    # 会话已存在，提示信息
    echo "会话 $SESSION_NAME 已存在，正在连接..."
fi

# 连接到会话
tmux attach -t "$SESSION_NAME"

之后启动时我们只需要运行这两个脚本即可。

要从会话中退出，请使用 Ctrl+b 然后输入 d。

结尾和碎碎念

这篇文章大概是我目前写过最长的一篇文章了。可能有读者已经发现了，很多地方都是对各种软件官方文档的照搬。但其实我写这篇文章的目的还是希望能够用自己摸索的经验来帮助更多之前从未接触过 Linux 和命令行的新人能够学习到一些基础的知识。

我从2024年初开始接触到 Linux 的时候就是因为搭 Bot时听说 NapCat 在 Linux 上运行更加稳定。于是便开始研究，但是我既不是科班出身，周边也完全没有人使用 Linux 系统。我完全可以说是自己完全抓瞎在黑暗里一个摸索出来一些基本的知识。在这个过程中，也遭受了部分人的闲言碎语，「不会 Linux 你用什么 Linux？」「这些都是基本的知识，你自己去看手册。」，然后一边去网上各种乱七八糟的资料里找到我需要的那一部分。可能是我不太聪明的缘故，大概在这种痛苦中挣扎了快两个月，才理解了一些比较底层的概念。

因此为了不让和当初的我一样初次接触 Linux 的新手面对无数学习资料感到无所适从，我写出了这篇文章。不解释多余的知识，但是讲清楚一些最基本最底层的概念来帮助新人理解大部分操作的意义，而不是只会复制粘贴代码然后对着报错发呆。

当然，由于我个人能力有限和种种因素，本文也难免存在一些不足和错误，还请各位读者批评指正。

希望大家都能搭出属于自己的 Bot。

前言