# harnessAgent

**Repository Path**: zzssheng/harness-agent

## Basic Information

- **Project Name**: harnessAgent
- **Description**: 没有什么好介绍的的点点滴滴
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 校园智能问答系统

## 目录结构

```
harnessAgent/
├── backend/
│   ├── .env                # 唯一配置入口（数据库 / Redis / JWT），不提交
│   ├── .env.example        # 配置模板
│   └── docker-compose.yml  # 开发依赖服务（PostgreSQL + Redis + Adminer）
├── web/                    # Vue 3 + TypeScript 前端（pnpm + Vite）
└── docker/initdb/          # PostgreSQL 初始化脚本（安装 vector 扩展）
```

## 安装依赖（首次运行，或依赖变更后）

```powershell
cd E:\zzs\harnessAgent\backend
uv sync

cd E:\zzs\harnessAgent\web
pnpm install
```

- 后端：`uv run` 也会自动同步，这一步写出来是为了明确、可排查。
- 前端：**必须**先 `pnpm install`，否则 `pnpm dev` 会报找不到 `vite`。

## 启动依赖服务

```powershell
cd E:\zzs\harnessAgent\backend
docker compose up -d
```

首次启动会自动创建数据库 `campus_qa` 并安装 `vector` 扩展。

## 启动后端

```powershell
cd backend
uv run uvicorn app.main:app --reload --port 8000
```

## 数据库迁移

核心就两条命令：

```powershell
cd E:\zzs\harnessAgent\backend

# 1) 生成迁移文件：改了 app/models/ 之后执行
uv run alembic revision --autogenerate -m "0001"

# 2) 执行迁移：新环境首次启动、或拉到别人新提交的迁移之后执行
uv run alembic upgrade head


生成管理员账号
cd E:\zzs\harnessAgent\backend
uv run python scripts/create_admin.py admin@example.com Admin123456
```

第 1 条执行完，先打开 `migrations/versions/` 下生成的新文件，确认没有误删字段或误改类型，再执行第 2 条。

其他常用命令：


| 命令                          | 作用                   |
| ----------------------------- | ---------------------- |
| `uv run alembic current`      | 当前库在哪个版本       |
| `uv run alembic history`      | 迁移历史               |
| `uv run alembic check`        | 模型与库结构是否有差异 |
| `uv run alembic downgrade -1` | 回退一个版本           |

`migrations/versions/` 下的文件**必须提交到 Git**，它们就是数据库结构的变更历史。

## 启动前端

```powershell
cd web
pnpm dev
```

前端和后端各开一个终端，两个都要运行。

## 访问地址


| 服务                  | 地址                         |
| --------------------- | ---------------------------- |
| 前端页面              | http://127.0.0.1:5173        |
| 后端接口文档          | http://127.0.0.1:8000/docs   |
| 后端健康检查          | http://127.0.0.1:8000/health |
| 数据库管理（Adminer） | http://127.0.0.1:7070        |

## 停止服务

在对应终端按 `Ctrl + C`；依赖服务用：

```powershell
cd E:\zzs\harnessAgent\backend
docker compose down
```

## 鉴权接口


| 方法 | 路径              | 说明                                                            |
| ---- | ----------------- | --------------------------------------------------------------- |
| POST | `/auth/register`  | 注册，JSON 提交                                                 |
| POST | `/auth/jwt/login` | 登录，**表单**提交 `username` / `password`，返回 `access_token` |
| GET  | `/users/me`       | 当前用户，需请求头`Authorization: Bearer <token>`               |

## 说明

- PostgreSQL 与 Redis 由 `backend/docker-compose.yml` 提供，数据存放在具名卷 `pgdata` / `redisdata` 中，`docker compose down` 不会丢数据。
- **所有配置集中在 `backend/.env`**：`DB_*` 同时供后端和 compose 使用，改一处即可；连接串由代码拼接，不写死 URL。
- 宿主机端口：PostgreSQL `5432`、Redis `6379`、Adminer `7070`；容器之间仍走 `postgres:5432` / `redis:6379`。
- 改 `.env` 后：后端要重启，compose 要 `docker compose up -d` 重建容器。
- `/health` 会返回数据库连通性和 pgvector 版本，可用来确认环境是否就绪。
- 前端默认端口 5173，后端默认端口 8000；前端要调后端接口，需在 `web/vite.config.ts` 配置 `/api` 代理（尚未配置）。