# data-sys

**Repository Path**: ecky88/data-sys

## Basic Information

- **Project Name**: data-sys
- **Description**: 简单的数据系统，快速进行表格数据管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# data-sys 智能体过程数据存放与统计分析系统

这是一个本地优先、后续可迁移服务器的动态数据表平台，面向智能体推广过程中的过程数据存放、API 接入、查询和统计分析。

## 当前能力

- 无登录版本，便于本地快速使用
- 通过 API 创建真实 PostgreSQL 数据表
- 自动记录表结构元数据
- 动态表数据写入、查询、修改、删除
- 基础统计：总数、分组统计、时间趋势、数值聚合
- API 使用说明页面
- Vue 3 管理页面
- 本地直跑与 Docker Compose 两套启动配置

## 技术栈

- 后端：FastAPI + SQLAlchemy Core
- 数据库：本地直跑默认 SQLite，Docker 部署默认 PostgreSQL
- 前端：Vue 3 + TypeScript + Element Plus + ECharts
- 部署：Docker Compose

## 运行方式边界

data-sys 当前有两套运行方式，参数不能混用：

| 运行方式 | 用途 | 前端端口 | 后端端口 | 数据库 | 配置来源 |
| --- | --- | ---: | ---: | --- | --- |
| 本地直跑 | JinFlow 本机开发/采样配套 | `6881` | `5955` | SQLite：`var/sqlite/data_sys.db` | 根目录 `.env` / `.env.example` |
| 标准部署 | 独立 data-sys 部署 | `5173` | `8000` | PostgreSQL Docker 命名卷 | `docker-compose.yml` / `DOCKER_*` |

标准部署不是本地直跑参数的简单换端口版；它由三套 Docker 服务/镜像组成：`postgres`、`backend`、`frontend`。本地直跑的 `FRONTEND_PORT`、`BACKEND_PORT`、`DB_TYPE=sqlite` 只服务于本机调试，不参与标准 Docker 部署。

## 快速启动

### 本地直跑：SQLite + 6881/5955

本地直跑使用根目录 `.env`，如果 `.env` 不存在，脚本会自动从 `.env.example` 复制一份。

默认配置：

- 前端页面：http://localhost:6881
- 后端 API：http://localhost:5955
- Swagger 文档：http://localhost:5955/docs
- 数据库：SQLite，文件位于 `var/sqlite/data_sys.db`

```powershell
cd data-sys
scripts\start-data-sys-local-env.bat
```

本地直跑需要 Node.js/npm；首次运行会在 `frontend` 下安装前端依赖。启动脚本会分别检查后端与前端健康状态，缺哪个启动哪个；后端/前端后台窗口会隐藏，日志在 `work/logs`。停止本地直跑服务：

```powershell
scripts\stop-data-sys-local-env.bat
```

如需调整本地端口或数据源，只改根目录 `.env`。该文件已被 Git 忽略，不会显示为待提交变更。

### 标准 Docker 部署：三服务/三镜像

确保已安装 Docker Desktop。

```bash
cd data-sys
docker compose up -d --build
```

访问：

- 前端页面：http://localhost:5173
- 后端 API：http://localhost:8000
- Swagger 文档：http://localhost:8000/docs

Docker 部署参数保留在 `docker-compose.yml` 的默认值中，不会被本地 `.env` 的 `FRONTEND_PORT`、`BACKEND_PORT`、`DB_TYPE` 污染。需要覆盖 Docker 部署参数时，使用 `DOCKER_*` 环境变量，例如 `DOCKER_FRONTEND_PORT`、`DOCKER_BACKEND_PORT`、`DOCKER_DB_TYPE`。

标准部署包含三项服务：

- `postgres`：PostgreSQL 数据库，默认使用 `postgres_data` 命名卷。
- `backend`：FastAPI 后端，容器内端口 `8000`。
- `frontend`：Vue 管理前端，容器内端口 `5173`。

## 目录约定

- `backend/migrations/`：可提交的数据库结构脚本和迁移参考。
- `var/sqlite/`：本地直跑生成的 SQLite 数据文件，已被 Git 忽略。
- Docker 数据：PostgreSQL 使用 `postgres_data` 命名卷，SQLite 使用 `sqlite_data` 命名卷。

## 手动本地开发启动

### 后端

```powershell
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 5955
```

### 前端

```powershell
cd frontend
npm install
$env:VITE_API_BASE_URL="http://localhost:5955"
npm run dev -- --host 0.0.0.0 --port 6881 --strictPort
```

## API 示例

下面示例以本地直跑默认后端端口 `5955` 为例；Docker 部署时将端口改为 `8000`。

### 创建数据表

```bash
curl -X POST http://localhost:5955/api/tables ^
  -H "Content-Type: application/json" ^
  -d "{\"table_name\":\"agent_call_logs\",\"display_name\":\"智能体调用记录\",\"columns\":[{\"name\":\"agent_key\",\"type\":\"string\",\"length\":100,\"nullable\":false},{\"name\":\"called_at\",\"type\":\"datetime\",\"nullable\":false},{\"name\":\"duration_ms\",\"type\":\"integer\",\"nullable\":true},{\"name\":\"success\",\"type\":\"boolean\",\"nullable\":false,\"default\":true}]}"
```

### 写入数据

```bash
curl -X POST http://localhost:5955/api/tables/agent_call_logs/records ^
  -H "Content-Type: application/json" ^
  -d "{\"agent_key\":\"data-web-dev-agent\",\"called_at\":\"2026-07-02T15:30:00+08:00\",\"duration_ms\":1200,\"success\":true}"
```

## 设计原则

- 动态数据表统一使用 `data_` 前缀，例如 `agent_call_logs` 实际表名为 `data_agent_call_logs`。
- 外部传入的表名、字段名、字段类型全部做白名单校验。
- 系统暂不提供登录，后续迁移服务器前建议增加 API Key 和管理员登录。