器人被各種門檻勸退？用 Docker 幾步搞定 AstrBot + NapCat + DeepSeek)
1. 為什么搭 QQ 機(jī)器人總在環(huán)境這一步卡住如果你搜過「Docker 部署 AstrBot NapCat DeepSeek QQ 機(jī)器人」這類關(guān)鍵詞大概率已經(jīng)看過不少教程但真正動(dòng)手時(shí)還是會(huì)被勸退。原因通常不在某一步特別難而是鏈路太長(zhǎng)QQ 登錄要處理協(xié)議、機(jī)器人框架要裝 Python 依賴、模型調(diào)用要配 Key、容器之間還要能互相通信。任何一環(huán)出問題表現(xiàn)都是「機(jī)器人不回消息」你根本不知道是 QQ 沒登上、OneBot 沒連上還是模型 Key 填錯(cuò)了。我自己的經(jīng)歷是最早用源碼方式裝 AstrBot光 Python 版本和依賴沖突就折騰了一晚上第二天換 Docker 才意識(shí)到這套組合真正的價(jià)值就是把「環(huán)境」這件事交給容器你只需要關(guān)心三樣?xùn)|西——NapCat 有沒有登上 QQ、AstrBot 有沒有連上 NapCat、模型 Key 有沒有生效。這三個(gè)問題各自都有明確的驗(yàn)證動(dòng)作跑通一次之后后面換模型、加插件、改人設(shè)都只是改配置。這篇要交付的就是這條完整鏈路用 Docker Compose 把 AstrBot 和 NapCat 一起拉起來NapCat 掃碼登錄 QQAstrBot 通過 OneBot 協(xié)議對(duì)接再把 DeepSeek 的模型接進(jìn)去最后用「容器健康檢查 → QQ 收發(fā)消息 → 模型回復(fù)確認(rèn)」三步驗(yàn)證。模型通道這塊我會(huì)用 TaoToken 統(tǒng)一管理 Key 和 API 地址這樣以后想換模型不用改一堆地方。適合誰看零基礎(chǔ)、想在 Windows 或 Linux 上用 Docker 跑一個(gè)能對(duì)話的 QQ 機(jī)器人、不想天天修環(huán)境的人。全程命令可復(fù)制配置片段可直接改。先說清楚三個(gè)組件各自干什么不然后面配置容易懵。NapCat 是基于 NTQQ 的 OneBot 協(xié)議實(shí)現(xiàn)通俗講它負(fù)責(zé)「登錄你的 QQ 并提供標(biāo)準(zhǔn)接口」把 QQ 的收發(fā)消息翻譯成 HTTP/WebSocket 接口。AstrBot 是 AI 聊天機(jī)器人框架負(fù)責(zé)接大模型、處理邏輯、管插件和人設(shè)它通過 OneBot 協(xié)議去調(diào)用 NapCat。DeepSeek 是模型提供方負(fù)責(zé)生成回復(fù)內(nèi)容。三者關(guān)系是QQ 用戶發(fā)消息 → NapCat 收到 → 通過 OneBot 轉(zhuǎn)給 AstrBot → AstrBot 調(diào)模型 → 回復(fù)經(jīng) NapCat 發(fā)回 QQ。理解了這條數(shù)據(jù)流排障就有方向了消息沒到 AstrBot查 NapCat 和 OneBot 連接AstrBot 收到了但不回復(fù)查模型 Key 和網(wǎng)絡(luò)回復(fù)內(nèi)容不對(duì)查人設(shè)和上下文。2. 用 TaoToken 統(tǒng)一模型 Key 與 API 通道在講 Docker 編排之前先把模型接入這塊理清楚因?yàn)樗鼪Q定了你后面配置 AstrBot 時(shí)填什么。很多人卡在模型這一步是因?yàn)槊總€(gè)模型廠商的 Key、Base URL、模型名都不一樣換一個(gè)模型就要改一次配置時(shí)間久了配置散落各處很難維護(hù)。我的做法是用 TaoToken 作為統(tǒng)一的模型接入通道。它的作用是給你一個(gè)統(tǒng)一的 API 地址和 Key背后可以對(duì)接 DeepSeek 等模型。對(duì) AstrBot 來說它只需要知道一個(gè) Base URL、一個(gè) Key、一個(gè) Model ID剩下的路由由 TaoToken 處理。這樣你以后想從 DeepSeek 換到別的模型只改 Model ID 就行不用動(dòng) Key 和地址。具體要準(zhǔn)備三樣?xùn)|西我把它叫「三件套」后面配置 AstrBot 時(shí)會(huì)反復(fù)用到配置項(xiàng)說明示例形態(tài)Base URL模型 API 的請(qǐng)求地址https://taotoken.net/apiAPI Key身份憑證形如 sk- 開頭sk-xxxxxxxxModel ID具體調(diào)用的模型標(biāo)識(shí)deepseek-chat獲取方式先訪問官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注冊(cè)賬號(hào)然后進(jìn)入控制臺(tái)創(chuàng)建 API Key。控制臺(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理頁面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。創(chuàng)建時(shí)給它起個(gè)能認(rèn)出來的名字比如 astrbot-qq方便以后區(qū)分。注意API Key 只在創(chuàng)建時(shí)完整顯示一次復(fù)制后先存到安全的地方。如果忘了直接刪掉重新建一個(gè)即可不用糾結(jié)。拿到 Key 之后建議先單獨(dú)驗(yàn)證一次確認(rèn)通道是通的再去配 AstrBot。這樣能把「模型通道問題」和「機(jī)器人配置問題」分開排障時(shí)省一半時(shí)間。驗(yàn)證可以用模型對(duì)話頁面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 直接發(fā)一句話測(cè)試也可以后面用 curl 驗(yàn)證。如果你打算長(zhǎng)期跑編碼類或 Agent 類任務(wù)可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 不過 QQ 機(jī)器人這種對(duì)話場(chǎng)景按量用 API 就夠了。這里要強(qiáng)調(diào)一點(diǎn)TaoToken 是模型接入通道不是替代 AstrBot 或 NapCat 的。NapCat 依然負(fù)責(zé) QQ 登錄AstrBot 依然負(fù)責(zé)機(jī)器人邏輯TaoToken 只解決「模型怎么調(diào)」這一層。三者職責(zé)別混配置時(shí)就不會(huì)亂。3. 可復(fù)制的 Docker Compose 配置這一節(jié)是核心給你一份可以直接改的 docker-compose 配置把 AstrBot 和 NapCat 一起編排起來。我不用一鍵腳本因?yàn)槟_本出問題時(shí)你不知道它改了什么用 compose 文件每一步都看得見改起來也清楚。先建目錄把配置放進(jìn)去mkdir -p ~/qq-bot cd ~/qq-bot然后創(chuàng)建docker-compose.yml內(nèi)容如下。注意端口映射和 volumes 路徑這兩個(gè)是最容易出錯(cuò)的地方services: napcat: image: mlikiowa/napcat-docker:latest container_name: napcat restart: unless-stopped environment: - NAPCAT_UID1000 - NAPCAT_GID1000 ports: - 6099:6099 # NapCat WebUI 登錄端口 - 3000:3000 # OneBot HTTP 接口 - 3001:3001 # OneBot WebSocket 接口 volumes: - ./napcat/config:/app/napcat/config - ./napcat/qq:/app/.config/QQ networks: - botnet astrbot: image: soulter/astrbot:latest container_name: astrbot restart: unless-stopped ports: - 6185:6185 # AstrBot WebUI 端口 volumes: - ./astrbot/data:/AstrBot/data environment: - TZAsia/Shanghai depends_on: - napcat networks: - botnet networks: botnet: driver: bridge幾個(gè)關(guān)鍵點(diǎn)解釋一下。restart: unless-stopped保證容器異常退出后自動(dòng)拉起機(jī)器人這種長(zhǎng)期跑的服務(wù)必須加。networks讓兩個(gè)容器在同一網(wǎng)絡(luò)里AstrBot 可以直接用服務(wù)名napcat訪問 NapCat不用管 IP。端口方面6099 是 NapCat 的 WebUI你掃碼登錄 QQ 用它3000/3001 是 OneBot 接口AstrBot 連它用6185 是 AstrBot 后臺(tái)。啟動(dòng)docker compose up -d啟動(dòng)后先做容器健康檢查這是三步驗(yàn)證的第一步docker compose ps正常的話兩個(gè)容器狀態(tài)都是Up。如果某個(gè)是Restarting或Exited看日志docker compose logs -f napcat docker compose logs -f astrbotNapCat 首次啟動(dòng)會(huì)初始化 QQ 環(huán)境日志里出現(xiàn)監(jiān)聽 6099 端口就算就緒。AstrBot 日志里出現(xiàn) WebUI 啟動(dòng)信息即可。這一步過了說明容器編排沒問題再往下走。提示如果你在 Linux 上跑注意 volumes 目錄權(quán)限。NapCat 容器內(nèi)以 UID 1000 運(yùn)行宿主機(jī)目錄如果權(quán)限不對(duì)會(huì)寫不進(jìn)去表現(xiàn)為登錄后配置不保存?？梢詂hown -R 1000:1000 ./napcat處理。4. 驗(yàn)證請(qǐng)求與成功結(jié)果容器起來后按三步驗(yàn)證走每步都有明確的成功標(biāo)志不要跳步。第一步容器健康檢查。上面docker compose ps兩個(gè) Up 就算過。再補(bǔ)一個(gè)端口檢查curl -I http://localhost:6099 curl -I http://localhost:6185能返回 HTTP 響應(yīng)頭就說明服務(wù)在監(jiān)聽。第二步QQ 收發(fā)消息。瀏覽器打開http://localhost:6099進(jìn)入 NapCat WebUI。首次登錄需要 TokenToken 在容器日志里docker compose logs napcat | grep -i token復(fù)制 Token 填進(jìn)頁面然后選「掃碼登錄」用手機(jī) QQ 掃碼。登錄成功后NapCat 就接管了這個(gè) QQ 賬號(hào)。此時(shí)用另一個(gè) QQ 號(hào)給機(jī)器人賬號(hào)發(fā)一條消息在 NapCat 的日志或消息列表里能看到這條消息說明 QQ 收發(fā)鏈路通了。第三步模型回復(fù)確認(rèn)?；氐?AstrBot 后臺(tái)http://localhost:6185默認(rèn)賬號(hào)密碼都是astrbot首次登錄會(huì)要求改密碼。登錄后做兩件事一是創(chuàng)建機(jī)器人消息平臺(tái)選 QQ 個(gè)人號(hào)OneBot啟用二是配置模型提供商把前面準(zhǔn)備的「三件套」填進(jìn)去。AstrBot 連 NapCat 的配置如果用 WebUI 填關(guān)鍵參數(shù)是{ platform: qq_official_or_onebot, onebot_ws_url: ws://napcat:3001, onebot_http_url: http://napcat:3000 }注意這里用的是容器服務(wù)名napcat不是 localhost因?yàn)?AstrBot 在容器里localhost 指向它自己。這是新手最容易踩的坑之一。模型提供商配置選 OpenAI 兼容類型填{ api_base: https://taotoken.net/api, api_key: sk-你的Key, model: deepseek-chat }保存后點(diǎn)「測(cè)試」返回成功即通道可用。然后用另一個(gè) QQ 號(hào)給機(jī)器人發(fā)「你好」如果收到模型生成的回復(fù)三步驗(yàn)證全部通過。到這一步你的 QQ 機(jī)器人已經(jīng)能對(duì)話了。如果模型測(cè)試通過但 QQ 不回復(fù)問題在 OneBot 連接如果 QQ 能收到消息但沒回復(fù)問題在模型配置。按這個(gè)二分法定位很快能找到。5. 本篇常見報(bào)錯(cuò)排查這一節(jié)按真實(shí)報(bào)錯(cuò)來都是這套組合里高頻出現(xiàn)的。401 Unauthorized。出現(xiàn)在模型測(cè)試或?qū)υ挄r(shí)。原因基本是 API Key 錯(cuò)了、過期或者 Base URL 填錯(cuò)。檢查api_base是不是https://taotoken.net/apiKey 有沒有多余空格。如果 Key 是在別處復(fù)制的重新在 API Keys 頁面建一個(gè)再試。local proxy failed / connection refused。AstrBot 連不上 NapCat。先確認(rèn) NapCat 容器在跑再確認(rèn) AstrBot 里填的是ws://napcat:3001而不是ws://localhost:3001。如果兩個(gè)容器不在同一 network服務(wù)名解析不了檢查 compose 里的 networks 配置是否兩邊都加了botnet。reading choices 相關(guān)報(bào)錯(cuò)。這是模型返回結(jié)構(gòu)解析失敗通常發(fā)生在 Base URL 指向了非 OpenAI 兼容接口或者 Model ID 寫錯(cuò)。確認(rèn) Model ID 是deepseek-chat這類有效值Base URL 用 TaoToken 的地址。如果換了模型Model ID 要同步改。OAuth / 登錄失敗。NapCat 掃碼登錄時(shí)報(bào)錯(cuò)多半是 QQ 版本或容器環(huán)境問題。先看 NapCat 日志具體報(bào)什么常見的是需要更新鏡像docker compose pull napcat docker compose up -d。另外掃碼用的手機(jī) QQ 和機(jī)器人賬號(hào)別是同一個(gè)否則會(huì)頂號(hào)。容器反復(fù)重啟?？慈罩径ㄎ?。NapCat 常見是 volumes 權(quán)限問題AstrBot 常見是 data 目錄被占用或損壞。權(quán)限問題按前面說的chown處理data 損壞可以備份后清空./astrbot/data重新初始化。消息能收到但不回復(fù)且模型測(cè)試正常。檢查 AstrBot 里機(jī)器人是否啟用、是否綁定了正確的模型提供商。有時(shí)候創(chuàng)建了機(jī)器人但沒啟用或者模型提供商沒設(shè)為默認(rèn)都會(huì)導(dǎo)致不回復(fù)。排障時(shí)記住一個(gè)原則先看日志再改配置。docker compose logs -f 服務(wù)名是最高頻的命令90% 的問題日志里直接寫了原因。如果你在接入文檔里找不到對(duì)應(yīng)說明可以查接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL、Key、Model ID 的完整說明。6. 后續(xù)擴(kuò)展與穩(wěn)定運(yùn)行建議跑通之后這套組合的可玩性才剛開始。AstrBot 支持人設(shè)切換、插件市場(chǎng)、MCP 服務(wù)NapCat 支持群管理、文件傳輸。但擴(kuò)展之前先把穩(wěn)定性做好不然加的功能越多越容易崩。第一把配置持久化確認(rèn)好。compose 里的 volumes 已經(jīng)映射了 NapCat 的 config 和 QQ 數(shù)據(jù)、AstrBot 的 data只要這兩個(gè)目錄在容器重建后登錄狀態(tài)和配置都還在。建議定期備份這兩個(gè)目錄。第二模型通道保持統(tǒng)一。既然用了 TaoToken 統(tǒng)一 Key 和地址就別再往 AstrBot 里塞多個(gè)廠商的 Key否則以后換模型又要翻配置。需要換模型時(shí)只改 Model ID 一個(gè)字段。第三人設(shè)和上下文管理。AstrBot 里切換人設(shè)后記得用/reset清空上下文否則舊人設(shè)的對(duì)話會(huì)影響新回復(fù)。這個(gè)細(xì)節(jié)很多人忽略導(dǎo)致「換了人設(shè)但感覺沒生效」。第四公網(wǎng)訪問要謹(jǐn)慎。如果你想讓管理后臺(tái)在外網(wǎng)也能訪問用內(nèi)網(wǎng)穿透工具時(shí)務(wù)必給后臺(tái)加密碼并且不要把 OneBot 接口直接暴露到公網(wǎng)否則別人可以拿你的機(jī)器人發(fā)消息。安全永遠(yuǎn)優(yōu)先于方便。第五長(zhǎng)期運(yùn)行建議用 Coding Plan 或按量 API 都行但要注意額度。QQ 機(jī)器人如果進(jìn)了活躍群消息量可能不小先在控制臺(tái)看用量避免超額?？刂婆_(tái) https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 里能看消耗。最后說個(gè)我踩過的坑一開始我把 AstrBot 和 NapCat 放在不同 compose 項(xiàng)目里結(jié)果網(wǎng)絡(luò)不通排查了半天。后來統(tǒng)一到一個(gè) compose、一個(gè) network問題消失。所以如果你要改配置盡量保持兩個(gè)服務(wù)在同一編排文件里省心。到這一步你的 Docker AstrBot NapCat DeepSeek QQ 機(jī)器人已經(jīng)完整跑通從容器編排到模型回復(fù)全鏈路驗(yàn)證過。后面想加插件、換人設(shè)、接 MCP都是在穩(wěn)定底座上做增量不會(huì)再被環(huán)境問題勸退。 搭 QQ 機(jī)器人被各種門檻勸退？用 Docker 幾步搞定 AstrBot + NapCat + DeepSeek
1. 為什么搭 QQ 機(jī)器人總在環(huán)境這一步卡住如果你搜過「Docker 部署 AstrBot NapCat DeepSeek QQ 機(jī)器人」這類關(guān)鍵詞大概率已經(jīng)看過不少教程但真正動(dòng)手時(shí)還是會(huì)被勸退。原因通常不在某一步特別難而是鏈路太長(zhǎng)QQ 登錄要處理協(xié)議、機(jī)器人框架要裝 Python 依賴、模型調(diào)用要配 Key、容器之間還要能互相通信。任何一環(huán)出問題表現(xiàn)都是「機(jī)器人不回消息」你根本不知道是 QQ 沒登上、OneBot 沒連上還是模型 Key 填錯(cuò)了。我自己的經(jīng)歷是最早用源碼方式裝 AstrBot光 Python 版本和依賴沖突就折騰了一晚上第二天換 Docker 才意識(shí)到這套組合真正的價(jià)值就是把「環(huán)境」這件事交給容器你只需要關(guān)心三樣?xùn)|西——NapCat 有沒有登上 QQ、AstrBot 有沒有連上 NapCat、模型 Key 有沒有生效。這三個(gè)問題各自都有明確的驗(yàn)證動(dòng)作跑通一次之后后面換模型、加插件、改人設(shè)都只是改配置。這篇要交付的就是這條完整鏈路用 Docker Compose 把 AstrBot 和 NapCat 一起拉起來NapCat 掃碼登錄 QQAstrBot 通過 OneBot 協(xié)議對(duì)接再把 DeepSeek 的模型接進(jìn)去最后用「容器健康檢查 → QQ 收發(fā)消息 → 模型回復(fù)確認(rèn)」三步驗(yàn)證。模型通道這塊我會(huì)用 TaoToken 統(tǒng)一管理 Key 和 API 地址這樣以后想換模型不用改一堆地方。適合誰看零基礎(chǔ)、想在 Windows 或 Linux 上用 Docker 跑一個(gè)能對(duì)話的 QQ 機(jī)器人、不想天天修環(huán)境的人。全程命令可復(fù)制配置片段可直接改。先說清楚三個(gè)組件各自干什么不然后面配置容易懵。NapCat 是基于 NTQQ 的 OneBot 協(xié)議實(shí)現(xiàn)通俗講它負(fù)責(zé)「登錄你的 QQ 并提供標(biāo)準(zhǔn)接口」把 QQ 的收發(fā)消息翻譯成 HTTP/WebSocket 接口。AstrBot 是 AI 聊天機(jī)器人框架負(fù)責(zé)接大模型、處理邏輯、管插件和人設(shè)它通過 OneBot 協(xié)議去調(diào)用 NapCat。DeepSeek 是模型提供方負(fù)責(zé)生成回復(fù)內(nèi)容。三者關(guān)系是QQ 用戶發(fā)消息 → NapCat 收到 → 通過 OneBot 轉(zhuǎn)給 AstrBot → AstrBot 調(diào)模型 → 回復(fù)經(jīng) NapCat 發(fā)回 QQ。理解了這條數(shù)據(jù)流排障就有方向了消息沒到 AstrBot查 NapCat 和 OneBot 連接AstrBot 收到了但不回復(fù)查模型 Key 和網(wǎng)絡(luò)回復(fù)內(nèi)容不對(duì)查人設(shè)和上下文。2. 用 TaoToken 統(tǒng)一模型 Key 與 API 通道在講 Docker 編排之前先把模型接入這塊理清楚因?yàn)樗鼪Q定了你后面配置 AstrBot 時(shí)填什么。很多人卡在模型這一步是因?yàn)槊總€(gè)模型廠商的 Key、Base URL、模型名都不一樣換一個(gè)模型就要改一次配置時(shí)間久了配置散落各處很難維護(hù)。我的做法是用 TaoToken 作為統(tǒng)一的模型接入通道。它的作用是給你一個(gè)統(tǒng)一的 API 地址和 Key背后可以對(duì)接 DeepSeek 等模型。對(duì) AstrBot 來說它只需要知道一個(gè) Base URL、一個(gè) Key、一個(gè) Model ID剩下的路由由 TaoToken 處理。這樣你以后想從 DeepSeek 換到別的模型只改 Model ID 就行不用動(dòng) Key 和地址。具體要準(zhǔn)備三樣?xùn)|西我把它叫「三件套」后面配置 AstrBot 時(shí)會(huì)反復(fù)用到配置項(xiàng)說明示例形態(tài)Base URL模型 API 的請(qǐng)求地址https://taotoken.net/apiAPI Key身份憑證形如 sk- 開頭sk-xxxxxxxxModel ID具體調(diào)用的模型標(biāo)識(shí)deepseek-chat獲取方式先訪問官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注冊(cè)賬號(hào)然后進(jìn)入控制臺(tái)創(chuàng)建 API Key。控制臺(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理頁面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。創(chuàng)建時(shí)給它起個(gè)能認(rèn)出來的名字比如 astrbot-qq方便以后區(qū)分。注意API Key 只在創(chuàng)建時(shí)完整顯示一次復(fù)制后先存到安全的地方。如果忘了直接刪掉重新建一個(gè)即可不用糾結(jié)。拿到 Key 之后建議先單獨(dú)驗(yàn)證一次確認(rèn)通道是通的再去配 AstrBot。這樣能把「模型通道問題」和「機(jī)器人配置問題」分開排障時(shí)省一半時(shí)間。驗(yàn)證可以用模型對(duì)話頁面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 直接發(fā)一句話測(cè)試也可以后面用 curl 驗(yàn)證。如果你打算長(zhǎng)期跑編碼類或 Agent 類任務(wù)可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 不過 QQ 機(jī)器人這種對(duì)話場(chǎng)景按量用 API 就夠了。這里要強(qiáng)調(diào)一點(diǎn)TaoToken 是模型接入通道不是替代 AstrBot 或 NapCat 的。NapCat 依然負(fù)責(zé) QQ 登錄AstrBot 依然負(fù)責(zé)機(jī)器人邏輯TaoToken 只解決「模型怎么調(diào)」這一層。三者職責(zé)別混配置時(shí)就不會(huì)亂。3. 可復(fù)制的 Docker Compose 配置這一節(jié)是核心給你一份可以直接改的 docker-compose 配置把 AstrBot 和 NapCat 一起編排起來。我不用一鍵腳本因?yàn)槟_本出問題時(shí)你不知道它改了什么用 compose 文件每一步都看得見改起來也清楚。先建目錄把配置放進(jìn)去mkdir -p ~/qq-bot cd ~/qq-bot然后創(chuàng)建docker-compose.yml內(nèi)容如下。注意端口映射和 volumes 路徑這兩個(gè)是最容易出錯(cuò)的地方services: napcat: image: mlikiowa/napcat-docker:latest container_name: napcat restart: unless-stopped environment: - NAPCAT_UID1000 - NAPCAT_GID1000 ports: - 6099:6099 # NapCat WebUI 登錄端口 - 3000:3000 # OneBot HTTP 接口 - 3001:3001 # OneBot WebSocket 接口 volumes: - ./napcat/config:/app/napcat/config - ./napcat/qq:/app/.config/QQ networks: - botnet astrbot: image: soulter/astrbot:latest container_name: astrbot restart: unless-stopped ports: - 6185:6185 # AstrBot WebUI 端口 volumes: - ./astrbot/data:/AstrBot/data environment: - TZAsia/Shanghai depends_on: - napcat networks: - botnet networks: botnet: driver: bridge幾個(gè)關(guān)鍵點(diǎn)解釋一下。restart: unless-stopped保證容器異常退出后自動(dòng)拉起機(jī)器人這種長(zhǎng)期跑的服務(wù)必須加。networks讓兩個(gè)容器在同一網(wǎng)絡(luò)里AstrBot 可以直接用服務(wù)名napcat訪問 NapCat不用管 IP。端口方面6099 是 NapCat 的 WebUI你掃碼登錄 QQ 用它3000/3001 是 OneBot 接口AstrBot 連它用6185 是 AstrBot 后臺(tái)。啟動(dòng)docker compose up -d啟動(dòng)后先做容器健康檢查這是三步驗(yàn)證的第一步docker compose ps正常的話兩個(gè)容器狀態(tài)都是Up。如果某個(gè)是Restarting或Exited看日志docker compose logs -f napcat docker compose logs -f astrbotNapCat 首次啟動(dòng)會(huì)初始化 QQ 環(huán)境日志里出現(xiàn)監(jiān)聽 6099 端口就算就緒。AstrBot 日志里出現(xiàn) WebUI 啟動(dòng)信息即可。這一步過了說明容器編排沒問題再往下走。提示如果你在 Linux 上跑注意 volumes 目錄權(quán)限。NapCat 容器內(nèi)以 UID 1000 運(yùn)行宿主機(jī)目錄如果權(quán)限不對(duì)會(huì)寫不進(jìn)去表現(xiàn)為登錄后配置不保存?？梢詂hown -R 1000:1000 ./napcat處理。4. 驗(yàn)證請(qǐng)求與成功結(jié)果容器起來后按三步驗(yàn)證走每步都有明確的成功標(biāo)志不要跳步。第一步容器健康檢查。上面docker compose ps兩個(gè) Up 就算過。再補(bǔ)一個(gè)端口檢查curl -I http://localhost:6099 curl -I http://localhost:6185能返回 HTTP 響應(yīng)頭就說明服務(wù)在監(jiān)聽。第二步QQ 收發(fā)消息。瀏覽器打開http://localhost:6099進(jìn)入 NapCat WebUI。首次登錄需要 TokenToken 在容器日志里docker compose logs napcat | grep -i token復(fù)制 Token 填進(jìn)頁面然后選「掃碼登錄」用手機(jī) QQ 掃碼。登錄成功后NapCat 就接管了這個(gè) QQ 賬號(hào)。此時(shí)用另一個(gè) QQ 號(hào)給機(jī)器人賬號(hào)發(fā)一條消息在 NapCat 的日志或消息列表里能看到這條消息說明 QQ 收發(fā)鏈路通了。第三步模型回復(fù)確認(rèn)?；氐?AstrBot 后臺(tái)http://localhost:6185默認(rèn)賬號(hào)密碼都是astrbot首次登錄會(huì)要求改密碼。登錄后做兩件事一是創(chuàng)建機(jī)器人消息平臺(tái)選 QQ 個(gè)人號(hào)OneBot啟用二是配置模型提供商把前面準(zhǔn)備的「三件套」填進(jìn)去。AstrBot 連 NapCat 的配置如果用 WebUI 填關(guān)鍵參數(shù)是{ platform: qq_official_or_onebot, onebot_ws_url: ws://napcat:3001, onebot_http_url: http://napcat:3000 }注意這里用的是容器服務(wù)名napcat不是 localhost因?yàn)?AstrBot 在容器里localhost 指向它自己。這是新手最容易踩的坑之一。模型提供商配置選 OpenAI 兼容類型填{ api_base: https://taotoken.net/api, api_key: sk-你的Key, model: deepseek-chat }保存后點(diǎn)「測(cè)試」返回成功即通道可用。然后用另一個(gè) QQ 號(hào)給機(jī)器人發(fā)「你好」如果收到模型生成的回復(fù)三步驗(yàn)證全部通過。到這一步你的 QQ 機(jī)器人已經(jīng)能對(duì)話了。如果模型測(cè)試通過但 QQ 不回復(fù)問題在 OneBot 連接如果 QQ 能收到消息但沒回復(fù)問題在模型配置。按這個(gè)二分法定位很快能找到。5. 本篇常見報(bào)錯(cuò)排查這一節(jié)按真實(shí)報(bào)錯(cuò)來都是這套組合里高頻出現(xiàn)的。401 Unauthorized。出現(xiàn)在模型測(cè)試或?qū)υ挄r(shí)。原因基本是 API Key 錯(cuò)了、過期或者 Base URL 填錯(cuò)。檢查api_base是不是https://taotoken.net/apiKey 有沒有多余空格。如果 Key 是在別處復(fù)制的重新在 API Keys 頁面建一個(gè)再試。local proxy failed / connection refused。AstrBot 連不上 NapCat。先確認(rèn) NapCat 容器在跑再確認(rèn) AstrBot 里填的是ws://napcat:3001而不是ws://localhost:3001。如果兩個(gè)容器不在同一 network服務(wù)名解析不了檢查 compose 里的 networks 配置是否兩邊都加了botnet。reading choices 相關(guān)報(bào)錯(cuò)。這是模型返回結(jié)構(gòu)解析失敗通常發(fā)生在 Base URL 指向了非 OpenAI 兼容接口或者 Model ID 寫錯(cuò)。確認(rèn) Model ID 是deepseek-chat這類有效值Base URL 用 TaoToken 的地址。如果換了模型Model ID 要同步改。OAuth / 登錄失敗。NapCat 掃碼登錄時(shí)報(bào)錯(cuò)多半是 QQ 版本或容器環(huán)境問題。先看 NapCat 日志具體報(bào)什么常見的是需要更新鏡像docker compose pull napcat docker compose up -d。另外掃碼用的手機(jī) QQ 和機(jī)器人賬號(hào)別是同一個(gè)否則會(huì)頂號(hào)。容器反復(fù)重啟?？慈罩径ㄎ?。NapCat 常見是 volumes 權(quán)限問題AstrBot 常見是 data 目錄被占用或損壞。權(quán)限問題按前面說的chown處理data 損壞可以備份后清空./astrbot/data重新初始化。消息能收到但不回復(fù)且模型測(cè)試正常。檢查 AstrBot 里機(jī)器人是否啟用、是否綁定了正確的模型提供商。有時(shí)候創(chuàng)建了機(jī)器人但沒啟用或者模型提供商沒設(shè)為默認(rèn)都會(huì)導(dǎo)致不回復(fù)。排障時(shí)記住一個(gè)原則先看日志再改配置。docker compose logs -f 服務(wù)名是最高頻的命令90% 的問題日志里直接寫了原因。如果你在接入文檔里找不到對(duì)應(yīng)說明可以查接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL、Key、Model ID 的完整說明。6. 后續(xù)擴(kuò)展與穩(wěn)定運(yùn)行建議跑通之后這套組合的可玩性才剛開始。AstrBot 支持人設(shè)切換、插件市場(chǎng)、MCP 服務(wù)NapCat 支持群管理、文件傳輸。但擴(kuò)展之前先把穩(wěn)定性做好不然加的功能越多越容易崩。第一把配置持久化確認(rèn)好。compose 里的 volumes 已經(jīng)映射了 NapCat 的 config 和 QQ 數(shù)據(jù)、AstrBot 的 data只要這兩個(gè)目錄在容器重建后登錄狀態(tài)和配置都還在。建議定期備份這兩個(gè)目錄。第二模型通道保持統(tǒng)一。既然用了 TaoToken 統(tǒng)一 Key 和地址就別再往 AstrBot 里塞多個(gè)廠商的 Key否則以后換模型又要翻配置。需要換模型時(shí)只改 Model ID 一個(gè)字段。第三人設(shè)和上下文管理。AstrBot 里切換人設(shè)后記得用/reset清空上下文否則舊人設(shè)的對(duì)話會(huì)影響新回復(fù)。這個(gè)細(xì)節(jié)很多人忽略導(dǎo)致「換了人設(shè)但感覺沒生效」。第四公網(wǎng)訪問要謹(jǐn)慎。如果你想讓管理后臺(tái)在外網(wǎng)也能訪問用內(nèi)網(wǎng)穿透工具時(shí)務(wù)必給后臺(tái)加密碼并且不要把 OneBot 接口直接暴露到公網(wǎng)否則別人可以拿你的機(jī)器人發(fā)消息。安全永遠(yuǎn)優(yōu)先于方便。第五長(zhǎng)期運(yùn)行建議用 Coding Plan 或按量 API 都行但要注意額度。QQ 機(jī)器人如果進(jìn)了活躍群消息量可能不小先在控制臺(tái)看用量避免超額?？刂婆_(tái) https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 里能看消耗。最后說個(gè)我踩過的坑一開始我把 AstrBot 和 NapCat 放在不同 compose 項(xiàng)目里結(jié)果網(wǎng)絡(luò)不通排查了半天。后來統(tǒng)一到一個(gè) compose、一個(gè) network問題消失。所以如果你要改配置盡量保持兩個(gè)服務(wù)在同一編排文件里省心。到這一步你的 Docker AstrBot NapCat DeepSeek QQ 機(jī)器人已經(jīng)完整跑通從容器編排到模型回復(fù)全鏈路驗(yàn)證過。后面想加插件、換人設(shè)、接 MCP都是在穩(wěn)定底座上做增量不會(huì)再被環(huán)境問題勸退。