team-acatche/cheshire
GitHub: team-acatche/cheshire
Cheshire 是一款基于 RAG 与大语言模型的项目文档安全合规性评估工具，帮助开发团队自动化检测文档合规问题。
Stars: 1 | Forks: 0
# cheshire
一款安全合规性评估工具，用于评估项目文档，赋能开发团队开发更安全的软件。
本项目使用 Docker 进行容器化，以提供一致且简便的开发环境配置。
## 快速开始 (Docker)
在 cheshire-backend 文件夹中创建一个 .env 文件并粘贴以下内容：
```
# 模式
MODE=ollama # ollama | together-ai
CONFIG_TYPE=rag # rag | full-document
# HuggingFace
HF_TOKEN=\
# Ollama
OLLAMA_URL=\
OLLAMA_EMBEDDING_MODEL=qwen3-embedding:0.6b
OLLAMA_CHAT_MODEL=qwen3
HF_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
# Exa
EXA_API_KEY=\
# Together AI
TOGETHER_API_KEY=\
TOGETHER_CHAT_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507-tput
TOGETHER_REASONING_EFFORT=high
```
使用单个命令运行整个项目：
```
docker compose up --build
```
## 服务
| 服务 | 描述 | URL |
| -------- | --------------------------- | ----------------------- |
| Frontend | 用户界面 (React/Vite) | `http://localhost:5173` |
| Backend | FastAPI 后端 API | `http://localhost:8000` |
## 健康检查
验证后端是否正在运行：
```
curl http://localhost:8000/healthcheck
```
## 🐳 Docker 设置
### 前置条件
* Docker
* Docker Compose
### 构建并运行
```
docker compose up --build
```
### 停止容器
```
docker compose down
```
## 项目结构
```
cheshire/
├── docker-compose.yml
├── README.md
├── cheshire-backend/
│ ├── Dockerfile
│ ├── pyproject.toml
│ ├── poetry.lock
│ └── src/
├── cheshire-frontend/
│ ├── Dockerfile
│ ├── package.json
│ └── src/
```
## 开发说明
* 后端基于 **FastAPI** 构建并使用 **Uvicorn** 运行
* Frontend 在独立的容器中运行，以便于模块化开发
* 各服务通过 Docker 网络进行通信
* 容器内的后端通过 `0.0.0.0` 访问，以确保正确暴露
## 已实现的功能
* Docker 化的后端服务
* Docker 化的前端服务
* 使用 Docker Compose 的多容器设置
* 后端健康检查 endpoint (`/healthcheck`)
* 通过后端日志验证了文档处理功能
## 已知限制
* UI 尚未包含处理/加载动画
## 如何测试
1. 运行：
docker compose up --build
2. 在浏览器中打开前端：`http://localhost:5173`
3. 测试后端：
curl http://localhost:8000/healthcheck
4. 查看 FastAPI 文档：`http://localhost:8000/docs`
5. 上传文档并监控后端日志：
docker compose logs -f cheshire-backend
## 生产环境部署
在生产环境中，你不需要使用 Vite 开发服务器。相反，你需要将前端**构建**为静态文件，并在 Docker 容器内使用 **nginx** 进行托管。然后你可以使用 **Cloudflare Tunnel** 将容器暴露到互联网——无需在你的机器上开放端口。
### 第一步：在前端 Dockerfile 中添加 nginx 阶段
前端 `Dockerfile` 已经具有一个用于创建静态文件的 `build` 阶段。请在 `cheshire-frontend/Dockerfile` 的末尾添加一个 `production` 阶段：
```
# ─────────────────────────────────────────────────────────────
# Stage 4: Production
# 使用 nginx 提供构建好的静态文件
# ─────────────────────────────────────────────────────────────
FROM nginx:alpine AS production
# 从 build stage 复制构建好的静态文件
COPY --from=build /app/dist /usr/share/nginx/html
# 复制自定义 nginx 配置
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
### 第二步：为你的 SPA 创建 nginx 配置
创建 `cheshire-frontend/nginx.conf`：
```
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
# Proxy API requests to the backend container.
# The path is preserved: /api/v1/evaluate → http://cheshire-backend:8000/api/v1/evaluate
location /api/ {
proxy_pass http://cheshire-backend:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# For single-page apps: if the file doesn't exist,
# serve index.html so React Router can handle the URL
location / {
try_files $uri $uri/ /index.html;
}
}
```
### 第三步：更新 docker-compose.yml 以适配生产环境
将前端服务的 target 修改为 `production` 阶段：
```
cheshire-frontend:
build:
context: ./cheshire-frontend
dockerfile: Dockerfile
target: production # was: development
container_name: cheshire-frontend
restart: unless-stopped
ports:
- "80:80" # nginx serves on port 80
depends_on:
- cheshire-backend
networks:
- cheshire
```
然后重新构建：
```
docker compose up --build
```
访问 `http://localhost` 以验证前端是否正常工作。
### 第四步：使用 Cloudflare Tunnel 暴露到互联网
如果你已经熟悉 Cloudflare Tunnel，可以跳过设置步骤。将你的 tunnel 指向容器：
```
# 如果您尚未登录：
cloudflared tunnel login
# 创建 tunnel（仅一次）：
cloudflared tunnel create cheshire
# 将您的域名路由到 tunnel：
cloudflared tunnel route dns cheshire cheshire.yourdomain.com
# 运行 tunnel，指向您的本地容器：
cloudflared tunnel run --url http://localhost:80 cheshire
```
这会将 `cheshire.yourdomain.com` -> 你的本地 80 端口 (nginx) -> 构建好的 React 应用进行代理。无需在你的路由器/防火墙上开放任何端口。
## 注意事项
* 在执行命令之前，请确保 Docker 正在运行
* 除非必要，否则避免使用 `--no-cache`，以防止占用大量存储空间
* 缓存目录已进行优化，以防止出现磁盘空间问题
## 相关任务
SCRUM-92 – 对应用进行 Docker 化，以提供更一致的环境并允许与其他服务进行集成
标签：AI风险缓解, AV绕过, FastAPI, RAG, React, Syscalls, 合规评估, 安全合规, 文档分析, 版权保护, 网络代理, 请求拦截, 逆向工具