NcatBot 文档

外观

装饰器与杂项工具

约 1242 字大约 4 分钟

2026-03-19

安全工具、进度条、GitHub 代理配置与环境变量参考

源码位置：ncatbot/utils/config/security.py、ncatbot/utils/logger/tqdm.py、ncatbot/utils/network.py

目录

1. 安全工具

源码位置：ncatbot/utils/config/security.py

from ncatbot.utils.config.security import strong_password_check, generate_strong_token

strong_password_check

检查密码是否满足强度策略。

def strong_password_check(password: str) -> bool
参数类型说明
passwordstr待检查的密码

强度策略：

  • 长度 ≥ 12
  • 包含数字
  • 包含大写字母
  • 包含小写字母
  • 包含特殊符号

允许的特殊字符：-_.~!()*（URI 安全字符集）

strong_password_check("abc")           # False — 太短
strong_password_check("Abcdef123456")  # False — 无特殊符号
strong_password_check("Abcdef1234_!")  # True

generate_strong_token

生成满足强度策略的随机 token。

def generate_strong_token(length: int = 16) -> str
参数类型默认值说明
lengthint16token 长度
token = generate_strong_token()     # 16 位随机 token
token = generate_strong_token(32)   # 32 位随机 token
assert strong_password_check(token) # 始终满足强度策略

安全自动修复

ConfigManager.get_security_issues(auto_fix=True) 会自动检测以下问题并修复：

检查项修复方式
ws_token 不满足强度策略自动调用 generate_strong_token() 替换
webui_token 不满足强度策略自动调用 generate_strong_token() 替换

修复后会自动调用 cm.save() 持久化。

2. tqdm 进度条

自定义 tqdm 包装，集成 NcatBot 配色方案。

源码位置：ncatbot/utils/logger/tqdm.py

from ncatbot.utils.logger.tqdm import tqdm

for item in tqdm(range(100), desc="处理中", colour="CYAN"):
    process(item)

参数

参数默认值说明
colour"GREEN"进度条颜色
bar_format内置模板自定义格式，包含百分比、计数、耗时
ncols80终端宽度

可用颜色

BLACK、RED、GREEN、YELLOW、BLUE、MAGENTA、CYAN、WHITE

与 download_file 集成

download_file 内部使用此 tqdm 包装显示下载进度：

from ncatbot.utils import download_file

download_file("https://example.com/large.zip", "large.zip")
# 处理中:  45%|████████████                | 45/100 [00:03<00:04, 12.50it/s]

3. GitHub 代理详解

源码位置：ncatbot/utils/network.py

用于在国内网络环境下加速 GitHub 资源访问。

from ncatbot.utils import get_proxy_url, gen_url_with_proxy

get_proxy_url

探测并返回可用 GitHub 代理 URL，结果缓存（后续调用直接返回缓存值）。

def get_proxy_url() -> str

返回空字符串表示直连。

gen_url_with_proxy

为 GitHub URL 添加代理前缀。

def gen_url_with_proxy(original_url: str) -> str
url = gen_url_with_proxy("https://github.com/user/repo/releases/latest")
# 可能返回: "https://proxy.example.com/https://github.com/user/repo/releases/latest"
# 或直连: "https://github.com/user/repo/releases/latest"

代理配置优先级

  1. 配置文件 — Config.github_proxy 字段（最高优先）
  2. 环境变量 — GITHUB_PROXY
  3. 自动探测 — get_proxy_url() 逐一测试内置代理列表

建议

  • 开发环境直接设置环境变量 GITHUB_PROXY，避免自动探测延迟
  • 生产环境在 config.yaml 的 github_proxy 字段指定固定代理

3.5 异步 HTTP 工具

源码位置：ncatbot/utils/network.py

提供基于 aiohttp 的异步下载和 HTTP 请求工具，支持标准 HTTP/SOCKS5 代理。

from ncatbot.utils import (
    async_download_to_file,
    async_download_to_bytes,
    async_http_get,
    async_check_proxy,
)

async_download_to_file

异步下载 URL 到目录，返回文件路径。

async def async_download_to_file(
    url: str,
    dest_dir: str | Path,
    *,
    filename: str | None = None,
    proxy: str | None = None,
) -> Path
参数类型说明
urlstr下载地址
dest_dirstr | Path目标目录，不存在时自动创建
filenamestr | None文件名，省略则从 URL 推断
proxystr | NoneHTTP/SOCKS5 代理地址

async_download_to_bytes

异步下载 URL 到内存，返回原始字节。

async def async_download_to_bytes(url: str, *, proxy: str | None = None) -> bytes

async_http_get

异步 GET 请求，返回响应体字节。

async def async_http_get(
    url: str,
    *,
    headers: dict | None = None,
    proxy: str | None = None,
    timeout: float = 10.0,
) -> bytes

async_check_proxy

检查 HTTP/SOCKS5 代理是否可用。

async def async_check_proxy(proxy_url: str) -> bool

通过代理请求 https://www.google.com/generate_204 验证连通性。

4. 配置 YAML 完整示例

# 基础配置
bot_uin: "1234567890"
root: "9876543210"
debug: false
websocket_timeout: 15
enable_webui_interaction: true
check_ncatbot_update: true
skip_ncatbot_install_check: false

# GitHub 代理（留空或删除此行使用自动探测）
github_proxy: "https://proxy.example.com"

# 标准 HTTP/SOCKS5 代理（用于 Attachment 下载、MiscAPI 请求等）
http_proxy: "http://127.0.0.1:7890"

# NapCat 连接配置
napcat:
  ws_uri: "ws://localhost:3001"
  ws_token: "your_strong_token_here"
  ws_listen_ip: "localhost"
  webui_uri: "http://localhost:6099"
  webui_token: "your_webui_token_here"
  enable_webui: true
  enable_update_check: false
  stop_napcat: false  # Linux 下关闭 Bot 时才会停止本机 NapCat
  skip_setup: false

# 插件配置
plugin:
  plugins_dir: "plugins"
  load_plugin: true
  plugin_whitelist: []           # 空=不过滤
  plugin_blacklist: []
  auto_install_pip_deps: true
  plugin_configs:
    my_plugin:
      key: value

5. 环境变量汇总

环境变量作用默认值使用方
NCATBOT_CONFIG_PATH配置文件路径./config.yamlConfigStorage
NCATBOT_BOT_UINBot QQ 号（仅 yaml 中无该键时生效）—ConfigStorage
NCATBOT_ROOT管理员 QQ 号（仅 yaml 中无该键时生效）—ConfigStorage
NCATBOT_NON_INTERACTIVE全局非交互模式（1/true/yes）falseis_interactive()
NCATBOT_SKIP_NAPCAT_INSTALL_CONFIRM跳过 NapCat 安装确认（1/true/yes/on）falseConfigManager
NCATBOT_SKIP_PIP_INSTALL_CONFIRM跳过 pip 依赖安装确认（1/true/yes/on）falseConfigManager
LOG_LEVEL控制台日志级别DEBUGsetup_logging
FILE_LOG_LEVEL文件日志级别DEBUGsetup_logging
LOG_FILE_PATH日志目录./logssetup_logging
BACKUP_COUNT日志保留天数7setup_logging
GITHUB_PROXYGitHub 代理地址—Config、get_proxy_url
HTTP_PROXY标准 HTTP/SOCKS5 代理地址—Config、Attachment、MiscAPI

设置示例

PowerShell：

$env:LOG_LEVEL = "INFO"
$env:GITHUB_PROXY = "https://proxy.example.com"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
python main.py

Linux / macOS：

export LOG_LEVEL=INFO
export GITHUB_PROXY=https://proxy.example.com
export HTTP_PROXY=http://127.0.0.1:7890
python main.py

.env 文件（需框架支持）：

LOG_LEVEL=INFO
FILE_LOG_LEVEL=DEBUG
LOG_FILE_PATH=./logs
BACKUP_COUNT=7
GITHUB_PROXY=https://proxy.example.com
HTTP_PROXY=http://127.0.0.1:7890

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot