---
title: napcat
canonical_url: "https://www.modelscope.ai/studios/hajimi/napcat"
md_url: "https://www.modelscope.ai/studios/hajimi/napcat.md"
repository: hajimi/napcat
chinese_name: NapCat
last_updated: 2026-10-21
sdk_type: docker
downloads: 0
stars: 0
---

# napcat

> napcat - An interactive demo by hajimi on ModelScope. NapCat with Cloudflare Tunnel, persistent workspace and r2sync GitHub backup

hajimi/napcat is an interactive demo (Studio) on ModelScope. built with docker. also known as 「NapCat」.

- **Repository**: hajimi/napcat
- **SDK**: docker
- **Downloads**: 0
- **Stars**: 0
- **Last updated**: 2026-10-21

Source: https://www.modelscope.ai/studios/hajimi/napcat

---

# NapCat · ModelScope 国际站

访问入口：**https://napcat.moyang1.top/webui/**

创空间：**https://modelscope.ai/studios/hajimi/napcat**

Docker 创空间只保存部署文件。QQ 和 NapCat 统一来自官方
[NapCatAppImageBuild 最新发行版](https://github.com/NapNeko/NapCatAppImageBuild/releases/latest)，
不再分别下载 QQ deb、NapCat Shell 或手工修改 QQ 入口。
cloudflared 与 r2sync 仍分别下载、在多阶段构建中编译。

## 架构

- NapCat WebUI：`0.0.0.0:7860`，使用平台 Secret 中的 `WEBUI_TOKEN` 登录。
- AppImage 在构建阶段校验 SHA-256 并解包到 `/opt/napcat`，运行官方 `AppRun`，
  由其管理 Xvfb；构建和运行均不需要 FUSE、特权容器或挂载权限。
- `AppRun` 工作目录固定为持久化的 `live/`，供 `NAPCAT_WORKDIR` 使用；
  QQ 登录目录和包内 config/plugins 也链接到原有持久化目录。
- Cloudflare Tunnel：HTTP/2 出站连接，远程路由应为
  `napcat.moyang1.top` → `http://localhost:7860`。
- 持久化数据：`/mnt/workspace/napcat/live/{qq,config,plugins}`。
- 二级备份：r2sync GitHub 模式，私有仓库 `MoYangking/napcat-data` 的 `main` 分支。
- WebUI 可配置 OneBot 的反向 WebSocket。额外的公网 OneBot 端口需要另配隧道路由。

## 平台 Secrets

| Key | 用途 |
| --- | --- |
| `TUNNEL_TOKEN` | Cloudflare Tunnel 运行令牌 |
| `R2SYNC_GITHUB_PAT` | 数据仓库 Contents 读写权限 |
| `WEBUI_TOKEN` | NapCat WebUI 登录口令 |
| `R2SYNC_ADMIN_PASSWORD` | r2sync 初始化管理口令 |

密钥仅在运行时注入；不会写入公开部署仓库或 Docker 构建参数。
本部署通过 `r2sync sync` 调度同步，未运行其独立管理 Web 服务。

## 备份与恢复

1. 本地 `live/` 数据存在时直接使用，启动不依赖 GitHub 网络，也不会被旧云端备份覆盖。
2. 本地没有 `live/` 时优先恢复持久化快照；两者均不存在时，先运行 r2sync 拉取 GitHub 快照再启动。
3. 本地数据不存在时验证快照 SHA-256，在临时目录完整恢复后原子迁入 `live/`。
   校验失败会阻止启动。不要单独删除 `.initialized` 标记。
4. WebUI 就绪后约 60 秒完成首次备份，之后每 30 分钟备份一次；失败每 60 秒重试。
5. 创建快照时短暂暂停 QQ 进程组，保留数据库及 WAL 文件的一致时间点；
   复制完成立即恢复 QQ，压缩和上传在运行期间完成。
6. 压缩快照分成 **48 MiB** 文件，通过 r2sync 提交和推送，避免单文件 100 MiB 限制。
   GitHub 保存完整最新快照；备份包含登录状态及配置，数据仓库应保持私有。
7. 正常收到停止信号后尝试最终备份；强制终止仍依赖持久化目录和最近一次成功备份。

Git 工作区和 r2sync 传输状态使用容器本地临时盘，每次进程启动重新初始化，避免
OSS/FUSE 挂载遗留 `index.lock` 阻塞启动。持久化快照与临时 Git 工作区分开，上传前
校验并复制快照；现有数据启动后再初始化远端传输，单次同步最多等待 10 分钟。
首次恢复只在本地缺少快照时采用远端版本。旧 `.r2sync` 目录不删除，
原有快照软链接继续可用，不触碰历史 Git 锁或未上传数据。

可选平台变量：`ACCOUNT`（快速登录 QQ 号）、`BACKUP_INTERVAL_SECONDS`（默认 1800）、
`R2SYNC_STORAGE_CAP_BYTES`（默认 4 GiB，当前快照大小上限，不包含 Git 历史大小）。
Git 历史会随快照变更增长，因此适合个人、小规模 QQ 数据；运行日志输出同步成功或失败状态。

## 更新

在魔搭中执行**重新构建/部署**即可更新，不需要改版本号。Docker 使用远程 `ADD`
重新验证 GitHub `/releases/latest` 清单；发布新版本后，清单变化会让 AppImage 安装层
缓存失效。不是把 `curl latest` 放在可能永久命中缓存的 `RUN` 中。

- 自动选择当前镜像架构对应的 `amd64` 或 `arm64` 产物。
- 校验发行版标签、下载源、文件大小和 GitHub 提供的 SHA-256；下载有超时和重试。
- 最新版本缺少对应产物、校验失败或 GitHub API 不可用时明确报错，**不静默回退旧版**。
- 构建日志输出实际版本；镜像内 `/opt/napcat/release.json` 记录版本、QQ 版本和哈希，
  启动日志也输出 `[version] NapCat AppImage ...`，便于确认升级结果。
- 普通重启只运行已经构建的版本，不会在启动时下载或替换程序。
- GitHub 公共 API 有匿名访问限额；触发限流时等待限额恢复后重新构建，勿把访问令牌写入 Dockerfile。

持久化目录和快照格式与旧部署保持兼容，普通重启/重建保留现有 QQ 登录、OneBot 配置、
插件和 WebUI 口令。空间迁移或重命名可能丢失平台存储，此时从 GitHub 快照恢复。

本空间由中国站迁移而来，沿用同一隧道和备份仓库。运行国际站时应保持
中国站 `MoYang303/napcat` 停止，避免双实例登录和并发写入备份。

本地回归测试（Linux / WSL）：

```sh
python3 -m unittest discover -s tests -v
```

上游：[NapCatQQ](https://github.com/NapNeko/NapCatQQ) ·
[r2sync](https://github.com/MoYangking/r2sync) ·
[cloudflared](https://github.com/cloudflare/cloudflared)