KingAkeem/twitterbot
GitHub: KingAkeem/twitterbot
一个基于 Go 和 React 构建的 Twitter/X 公开数据 OSINT 查看器，通过 GUI 界面查询用户资料、帖子、粉丝和关注信息，支持无凭证的演示模式与基于 Twitter API 的授权查询模式。
Stars: 6 | Forks: 2
# twitterbot
## 关于
twitterbot 是一个 API 优先的开源情报（OSINT）查看器，专为授权的 Twitter/X 公开数据研究而设计。它提供了一个基于 Go API 支持的 React UI，用于查询：
- 用户资料信息，例如姓名、位置、个人简介和认证状态
- 最近的帖子
- 粉丝
- 关注
它不会抓取或自动化实时社交媒体页面。一种基于固定数据（fixture）的演示模式可以在没有 Twitter/X 凭证的情况下运行相同的本地 API 契约。
## 无需凭证的演示
在本地启动这两个服务：
```
./scripts/dev.sh
```
当没有设置 `API_TOKEN` 时，脚本会自动选择 `TWITTERBOT_MODE=demo`。打开 `http://localhost:3000`，并在个人资料、帖子、粉丝和关注视图中使用预填的 `demo_analyst` 用户名。所有响应均来自 `pkg/demo/fixtures/` 下的本地内置固定数据。
Docker Compose 也默认使用演示模式：
```
docker compose up --build
```
## 环境要求
API 模式需要具有该应用所用端点访问权限的 Twitter API bearer token。演示模式不需要凭证或外部服务。
对于基于 Docker 的开发：
- Docker
- Docker Compose
对于不使用 Docker 的本地开发：
- Go
- Node.js 和 npm
你可以通过以下方式安装缺失的本地开发依赖：
```
./scripts/bootstrap.sh
```
若要同时尝试安装 Docker 和 Docker Compose：
```
./scripts/bootstrap.sh --with-docker
```
如果你的包管理器无法连接到镜像源，可以跳过 Go/Node/npm 的安装并使用上游直接下载链接：
```
./scripts/bootstrap.sh --direct
```
引导脚本支持常见的 Linux 包管理器和 Homebrew。在需要安装系统包时，它可能会提示要求 `sudo` 权限。
在 Ubuntu/Debian 上，该脚本会强制 `apt` 使用 IPv4 并重试下载。这可以避免一种常见错误：包镜像源在无法路由 IPv6 的网络上解析了 IPv6 地址。
在 Linux 上，该脚本还会提高 React 工具使用的 inotify watcher 限制。开发脚本默认启用了轮询，因此 `ENOSPC: System limit for number of file watchers reached` 不应阻止前端启动。
## 配置
在仓库根目录下创建一个 `.env` 文件供 Docker Compose 使用：
```
TWITTERBOT_MODE="api"
API_TOKEN="your-twitter-bearer-token"
BASE_URL="https://api.twitter.com/2"
TOKEN_URL="https://api.twitter.com/2/oauth2/token"
PORT=":8081"
```
对于本地开发，你可以在 `conf/twitterbot.env` 中使用相同的值：
```
TWITTERBOT_MODE="api"
API_TOKEN="your-twitter-bearer-token"
BASE_URL="https://api.twitter.com/2"
TOKEN_URL="https://api.twitter.com/2/oauth2/token"
PORT=":8081"
```
仅在你使用 OAuth 辅助流程时才需要 `CLIENT_SECRET`。
`TWITTERBOT_MODE` 接受 `api` 或 `demo`。当选择了 API 模式但未配置 `API_TOKEN` 时，后端会拒绝连接（fail closed）；它永远不会回退到抓取页面数据的方式。
## 使用 Docker 运行
Docker Compose 是在演示模式下同时启动后端和前端的最简单方法：
```
docker compose up --build
```
对于基于 API 的运行方式：
```
TWITTERBOT_MODE=api API_TOKEN="your-twitter-bearer-token" docker compose up --build
```
然后打开：
- 前端：`http://localhost:3000`
- 后端：`http://localhost:8081`
## 本地运行
如果需要，请先安装缺失的依赖：
```
./scripts/bootstrap.sh
```
然后同时启动 Go 后端和 React 前端：
```
./scripts/dev.sh
```
该脚本会在文件存在时加载 `conf/twitterbot.env`，在需要时安装前端依赖，在 `localhost:8081` 启动后端，并在 `localhost:3000` 启动前端。当设置了 `API_TOKEN` 时，它会选择 API 模式，否则选择演示模式；显式设置的 `TWITTERBOT_MODE` 优先级最高。
如果你更倾向于使用原生文件监视而不是轮询，请运行：
```
CHOKIDAR_USEPOLLING=false WATCHPACK_POLLING=false ./scripts/dev.sh
```
你依然可以手动运行每个服务：
```
go run ./cmd/main
```
```
cd front-end
npm install
npm start
```
## 前端 API URL
前端默认连接到 `http://localhost:8081`。可以通过以下方式覆盖：
```
REACT_APP_API_BASE_URL="http://localhost:8081"
```
## 测试和构建
在安装前端依赖之前运行后端检查。这可以防止 Go 扫描到 npm 可能放置在 `front-end/node_modules` 下的包。
后端：
```
go test ./cmd/... ./pkg/...
go build -o /tmp/twitterbot ./cmd/main
TWITTERBOT_MODE=demo PORT=:8081 /tmp/twitterbot
```
在另一个终端中，对基于固定数据的 API 进行冒烟测试：
```
curl http://localhost:8081/meta
curl http://localhost:8081/user/demo_analyst
```
前端：
```
cd front-end
npm ci
npm test -- --watchAll=false
npm run build
```
前端测试仅使用已提交的固定数据对本地 Go API 契约进行 Mock。它们不会访问 Twitter/X，也不依赖于实时的第三方页面标记。有关选择器和浏览器测试的指导，请参阅[弹性 UI 测试计划](docs/ui-testing.md)。
## CI/CD
`.github/workflows/ci.yml` 会在拉取请求（pull request）、推送到 `main` 或 `master` 分支以及手动触发时运行。它包含独立的后端和前端作业，随后会构建后端和前端 Docker 镜像，并验证 `docker-compose.yml`。
后端作业会运行基于固定数据的演示模式测试，并启动已编译的 API，以确保其运行时间足以确认 `/user/demo_analyst` 能正确响应。前端作业使用 `npm ci`，以非监视（non-watch）模式运行 React 测试套件，并构建生产环境包。
## 负责任地使用
- 仅使用获得了目标端点授权的凭证和访问权限来运行 API 模式，并遵守平台条款及适用法律。
- 收集公开数据仅限用于合法且经授权的目的。尽量减少请求、保留和导出的数据，尤其是关系数据。
- 请勿将此项目用于骚扰、监视、凭证收集、绕过访问控制或试图识别私人身份等用途。
- 将演示、自动化测试和截图保留在本地固定数据上。请勿将浏览器自动化工具指向实时的社交媒体页面。
标签：ESC4, EVTX分析, Go, MITM代理, OSINT, React, Ruby工具, Syscalls, 日志审计, 版权保护, 社交媒体分析, 请求拦截