远程访问指南

概述

本文档说明如何配置 CountBot 实现远程访问，涵盖以下场景：

场景	说明
局域网访问	从局域网内其他设备访问本机 CountBot
公网访问	通过反向代理或内网穿透暴露到公网
远程初始化	未本地初始化时，如何远程完成首次账号设置

一、局域网访问配置

1.1 启动参数

默认情况下，CountBot 仅监听本机回环地址，外网无法访问：

监听地址：127.0.0.1:8000
仅本机可访问

1.2 源码版本配置方法

方法一：环境变量（推荐）

通过环境变量 COUNTBOT_HOST=0.0.0.0 开启远程访问。

Linux/macOS

COUNTBOT_HOST=0.0.0.0 python start_app.py

Windows PowerShell

$env:COUNTBOT_HOST = "0.0.0.0"; python start_app.py

Windows CMD

set COUNTBOT_HOST=0.0.0.0
python start_app.py

方法二：直接修改源码

修改 backend/utils/runtime_env.py 中的默认值：

# 文件：backend/utils/runtime_env.py

DEFAULT_BIND_HOST = "127.0.0.1"  # ← 修改为 "0.0.0.0"
DEFAULT_BIND_PORT = 8000

修改后启动脚本会自动读取新的默认值，无需每次设置环境变量。

方法三：修改启动脚本

在 start_app.py 开头直接指定：

# 文件：start_app.py（开头添加）
import os
os.environ["COUNTBOT_HOST"] = "0.0.0.0"
os.environ["COUNTBOT_PORT"] = "8000"

文件	用途	支持环境变量
`start_app.py`	浏览器模式启动	✅
`start_desktop.py`	桌面窗口模式启动	✅
`start_dev.py`	开发模式启动（热重载）	✅

修改监听地址

自定义端口

# 同时设置主机和端口
COUNTBOT_HOST=0.0.0.0 COUNTBOT_PORT=9000 python start_app.py

Windows PowerShell

$env:COUNTBOT_HOST = "0.0.0.0"; $env:COUNTBOT_PORT = "9000"; python start_app.py

1.3 桌面预编译版说明

::: warning 重要提示桌面预编译版本（如 .exe 安装包）不支持通过环境变量修改监听地址。

桌面预编译版将 Python 环境和脚本打包，运行时不显示终端窗口，无法设置环境变量。

如需远程访问，请使用源码版本。 :::

桌面预编译版的特点：

单文件/单目录分发，开箱即用
无需安装 Python 环境
监听地址固定为 127.0.0.1:8000
无法修改为远程访问模式

解决方案：

下载源码版本，手动配置 Python 环境
使用反向代理方案
使用内网穿透工具将本地端口暴露出去

1.4 验证配置

启动后观察日志，确认输出包含 Network 地址：

============================================================
CountBot 启动中...
============================================================
服务器启动完成！
============================================================
Local:   http://localhost:8000
Network: http://192.168.1.100:8000    ← 局域网可访问此地址
------------------------------------------------------------

注意：Network 显示的是本机局域网 IP。从局域网内任意设备访问 http://<本机IP>:8000 即可。

二、公网访问配置

2.1 推荐架构

Internet → 反向代理(Nginx/Caddy) → CountBot (127.0.0.1:8000)

2.2 Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;

    # 替换为你的 CountBot 服务器地址
    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }

    location /ws/chat {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

关键点：反向代理与 CountBot 在同一台机器时，CountBot 仍会将带代理头的请求识别为远程访问，不会绕过认证。

2.3 内网穿透方案

如需绕过路由器端口映射限制，可使用内网穿透工具：

工具	特点
frp	功能强大，需要有公网服务器
ngrok	配置简单，有免费额度
cpolar	国内服务，配置简单

frp 客户端配置示例 (frpc.ini)：

[countbot]
type = tcp
local_ip = 127.0.0.1
local_port = 8000
remote_port = 8000

2.4 公网安全建议

启用 HTTPS（必需）
- 使用 Let's Encrypt 免费证书
- 或使用 Cloudflare 等 CDN 提供 HTTPS

配置防火墙

# 仅允许 80/443 端口入站
ufw allow 80/tcp
ufw allow 443/tcp
ufw deny 8000/tcp   # 关闭直接访问

定期查看日志

# 关注异常访问
tail -f countbot.log | grep -E "(AUTH|401|403)"

三、远程初始化

3.1 问题背景

新部署的 CountBot 需要先设置管理员账号才能使用。在已完成初始化的实例上，远程访问会跳转到登录页。

但如果实例从未初始化过（未设置密码），远程访问 API 会返回 AUTH_SETUP_REQUIRED，此时需要通过特殊路径完成首次设置。

3.2 启动时生成临时入口

首次启动未初始化时，系统自动生成带随机密钥的初始化路径：

/setup/<8位随机字符>

示例：

远程首次初始化入口：将此路径拼接到上方 Network 地址后访问
（有效期 30 分钟，初始化成功后立即失效）
→ /setup/akLRzvlW

3.3 操作步骤

步骤 1：启动 CountBot（源码版本）

COUNTBOT_HOST=0.0.0.0 python start_app.py

步骤 2：找到初始化路径

在启动日志中查找类似以下内容：

→ /setup/akLRzvlW

步骤 3：拼接完整 URL

将路径添加到 Network 地址后：

http://192.168.1.100:8000/setup/akLRzvlW

步骤 4：浏览器访问并设置账号

在浏览器打开上述 URL
输入用户名和密码
点击确认

步骤 5：验证成功

初始化成功后：

自动跳转到登录页
使用刚设置的账号密码登录
临时入口立即失效

3.4 临时入口有效期

配置项	说明
环境变量	`REMOTE_SETUP_SECRET_TTL_MINUTES`
默认值	30 分钟
有效范围	10 ~ 120 分钟
过期后	自动生成新的随机路径

示例：设置 45 分钟有效期

# Linux/macOS
REMOTE_SETUP_SECRET_TTL_MINUTES=45 COUNTBOT_HOST=0.0.0.0 python start_app.py

# Windows PowerShell
$env:REMOTE_SETUP_SECRET_TTL_MINUTES = "45"; $env:COUNTBOT_HOST = "0.0.0.0"; python start_app.py

3.5 注意事项

临时入口一次性使用：初始化成功后立即失效
任何能看到启动日志的人都有可能访问该入口
不要将启动日志分享给无关人员
建议配合 HTTPS + 防火墙使用

四、认证机制说明

4.1 受保护的端点

远程访问时，以下端点需要认证：

端点	说明
`/api/*`	所有 API 接口
`/ws/chat`	WebSocket 聊天接口

4.2 公开端点（无需认证）

端点	说明
`/api/auth/status`	查询认证状态
`/api/auth/login`	登录
`/api/auth/setup`	仅限本地或持有临时密钥
`/api/health`	健康检查
`/api/system/health`	系统健康检查

4.3 认证方式

方式一：Cookie 认证（浏览器）

正常登录后，Cookie 中会包含认证信息，后续请求自动携带。

方式二：Token 认证（API 调用）

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}'

响应头会返回 Cookie，也可使用 Bearer Token：

curl http://localhost:8000/api/chat/message \
  -H "Authorization: Bearer <token>"

4.4 WebSocket 认证

WebSocket 连接需要单独认证：

// 获取 Token 后连接
const token = "your-bearer-token";
const ws = new WebSocket("ws://localhost:8000/ws/chat", {
  headers: { "Authorization": `Bearer ${token}` }
});

五、常见问题

Q1: 启动后 `Network` 地址无法访问？

检查项：

防火墙是否放行该端口？

# Linux
sudo ufw allow 8000/tcp

# Windows 防火墙
netsh advfirewall firewall add rule name="CountBot" action=allow protocol=tcp localport=8000

是否跨网段访问？路由器是否允许设备间通信？

Q2: 提示 `AUTH_SETUP_REQUIRED`？

原因：服务尚未初始化密码。

解决：

在本机访问 http://localhost:8000 完成初始化
或使用启动日志中的 /setup/<密钥> 路径远程初始化

Q3: `/setup/<路径>` 返回 404？

可能原因：

路径拼写错误
临时入口已过期（默认30分钟）
已成功初始化过（入口自动失效）
服务已完成初始化，不再需要该入口

Q4: 根路径能打开但 API 返回 401？

正常现象。前端静态资源无需认证，但 API 接口受保护。

Q5: WebSocket 连接失败？

确认已通过 /api/auth/login 获取认证
检查是否传递了正确的 Cookie 或 Token
确认反向代理正确配置了 WebSocket 支持

Q6: 反向代理后仍提示需要登录？

原因：代理未正确传递认证头。

解决：确保代理配置包含以下头：

proxy_set_header Authorization $http_authorization;

Q7: 桌面预编译版能否开启远程访问？

不能。桌面预编译版（如 .exe 安装包）不支持修改监听地址。

解决方案：

使用源码版本 (start_app.py)
使用反向代理暴露端口
使用内网穿透工具

六、配置参考

6.1 环境变量

变量	默认值	说明
`COUNTBOT_HOST`	`127.0.0.1`	监听地址
`COUNTBOT_PORT`	`8000`	监听端口
`REMOTE_SETUP_SECRET_TTL_MINUTES`	`30`	临时入口有效期（分钟）

6.2 相关源码文件

文件	路径	说明
启动脚本	`start_app.py`	浏览器模式启动入口
启动脚本	`start_desktop.py`	桌面窗口模式启动入口
启动脚本	`start_dev.py`	开发模式启动入口（热重载）
环境变量处理	`backend/utils/runtime_env.py`	读取 `COUNTBOT_HOST`/`COUNTBOT_PORT`，定义默认值
认证中间件	`backend/modules/auth/middleware.py`	远程访问认证逻辑
认证路由	`backend/modules/auth/router.py`	认证 API 端点
应用入口	`backend/app.py`	FastAPI 应用和路由注册

6.3 日志关键信息

启动成功后，关注以下日志：

# 监听地址信息
Local:   http://localhost:8000        # 本机访问
Network: http://192.168.1.100:8000    # 局域网访问

# 未初始化时
远程首次初始化入口 → /setup/akLRzvlW  # 临时初始化路径

概述​

一、局域网访问配置​

1.1 启动参数​

1.2 源码版本配置方法​

方法一：环境变量（推荐）​

方法二：直接修改源码​

方法三：修改启动脚本​

相关启动脚本​

修改监听地址​

1.3 桌面预编译版说明​

1.4 验证配置​

二、公网访问配置​

2.1 推荐架构​

2.2 Nginx 配置示例​

2.3 内网穿透方案​

2.4 公网安全建议​

三、远程初始化​

3.1 问题背景​

3.2 启动时生成临时入口​

3.3 操作步骤​

3.4 临时入口有效期​

3.5 注意事项​

四、认证机制说明​

4.1 受保护的端点​

4.2 公开端点（无需认证）​

4.3 认证方式​

4.4 WebSocket 认证​

五、常见问题​

Q1: 启动后 Network 地址无法访问？​

Q2: 提示 AUTH_SETUP_REQUIRED？​

Q3: /setup/<路径> 返回 404？​

Q4: 根路径能打开但 API 返回 401？​

Q5: WebSocket 连接失败？​

Q6: 反向代理后仍提示需要登录？​

Q7: 桌面预编译版能否开启远程访问？​

六、配置参考​

6.1 环境变量​

6.2 相关源码文件​

6.3 日志关键信息​

七、相关文档​

概述