# SftpAudit

**Repository Path**: educloudtest/sftp-audit

## Basic Information

- **Project Name**: SftpAudit
- **Description**: sftp审计管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-26
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 江苏和教育 SFTP 文件交互管理系统

SFTP 文件操作审计平台：从 Elasticsearch 读取 SFTP 操作日志做聚合展示，用户账号与登录审计存在 MySQL。前后端分离，前端为 Vue 3 单页应用，后端只提供 RESTful JSON 接口。

## 技术栈

| 层 | 选型 |
|---|---|
| 前端 | Vue 3（`<script setup>`）+ Vite + Pinia + Vue Router + Bootstrap 5 |
| 后端 | Python 3.11 + FastAPI + SQLAlchemy 2（asyncio）+ Alembic |
| 数据 | MySQL 8（`sys_user` / `sys_login_log`）、Elasticsearch（SFTP 操作日志，只读） |

## 目录结构

```text
backend/          FastAPI 服务
  app/api         接口层（auth / sftp / users）
  app/services    聚合与缓存、登录限流
  app/es          Elasticsearch 扫描与查询
  app/models      SQLAlchemy 模型
  alembic/        迁移脚本
  scripts/        建表、灌管理员账号、生产初始化、探测脚本
  tests/          pytest 用例（sqlite 内存库，不依赖外部服务）
frontend/         Vite + Vue 3 单页应用
script/           本地重启、发布、自检脚本
docs/             部署手册、发布方案、PRD 与实施计划
```

## 本地开发

后端（需要 Python 3.11）：

```bash
cd backend
python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt
cp .env.example .env          # 再准备 .es.env，两文件都含密钥，已在 .gitignore 中
python -m alembic upgrade head          # 或 mysql -u root -p < scripts/schema.sql
python scripts/seed_admin.py --username admin   # 首次创建管理员（口令不回显）
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

前端：

```bash
cd frontend
npm install
npm run dev                   # 已配置 /api 代理到 http://127.0.0.1:8000
```

健康检查：`GET /healthz`（进程存活）、`GET /readyz`（实际探测数据库与 ES，200 才算就绪）。

## 自检与重启

```bash
python script/check_all.py            # ruff + pytest + 前端构建
python script/check_all.py --quick    # 只跑后端检查
python script/restart_backend.py      # 停旧进程 → 后台启动 → 探活 /healthz
```

发布流程见 [docs/部署手册-2026-10-30.md](docs/部署手册-2026-10-30.md) 与 [docs/Jenkins发布方案-2026-10-30.md](docs/Jenkins发布方案-2026-10-30.md)，发布机执行 `script/start-backend.sh`。

## 关键约定

- **时区**：数据库里的 `DATETIME` 存的是 UTC naive 时间；接口入参不带时区时按应用时区（`Asia/Shanghai`）解释，见 `backend/app/core/timeutil.py`。
- **角色**：`sys_user.role` 取值为 `admin` / `auditor`；`auditor` 在界面上显示为“管理员”，前端菜单与路由按 `role` 判定，不按用户名。
- **Elasticsearch 只读**：本系统只查询与聚合 ES 中的 SFTP 日志，不写入、不改索引。
- **密钥**：`.env` / `.es.env` / 数据库口令只保存在运维侧，不写入文档与仓库；生产环境启动时会拒绝仍为模板占位值的 `JWT_SECRET` / `DATABASE_URL`。
- **登录限流**：`LoginGuard` 只在单进程内计数，多 worker 部署需要换成共享存储才能作为强约束。