更新README.md
This commit is contained in:
qing committed
1 parent
3c8531f665
commit
290332c70c
3 files changed
+328
-126
No files matched your search
@@ -1,7 +1,7 @@
|
|||||||
# micro_servers
|
# micro_servers
|
||||||
|
|
||||||
一套 DIY 的轻量级微服务架构（UniServe Framework），由 C++ 与 Python 混合实现。
|
一套 DIY 的轻量级微服务架构（UniServe Framework），由 C++ 与 Python 混合实现。
|
||||||
`core` 作为进程托管服务负责拉起并守护各业务子进程，`gateway` 作为应用层网关统一鉴权与反向代理，`static` 与 `dnfs` 作为两个独立的业务服务对外提供能力。
|
`core` 作为进程托管服务负责拉起并守护各业务子进程，`gateway` 作为应用层网关统一鉴权与反向代理，`db` 提供通用数据库访问，`ai_review` 提供 AI 内容审核，`static` 与 `dnfs` 作为业务服务对外提供能力。
|
||||||
|
|
||||||
## 架构总览
|
## 架构总览
|
||||||
|
|
||||||
@@ -12,62 +12,84 @@
|
|||||||
│ 读取 init.txt 拉起并守护下列子进程 │
|
│ 读取 init.txt 拉起并守护下列子进程 │
|
||||||
└───────────────┬──────────────────────────────┘
|
└───────────────┬──────────────────────────────┘
|
||||||
│ 启动 / 守护
|
│ 启动 / 守护
|
||||||
┌───────────────────────┼───────────────────────┐
|
┌──────────────────┬───────────┼───────────┬──────────────────┐
|
||||||
▼ ▼ ▼
|
▼ ▼ ▼ ▼ ▼
|
||||||
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
┌──────────────┐ ┌──────────────┐ ┌────────┐ ┌──────────────┐ ┌──────────────┐
|
||||||
│ gateway │ │ static │ │ dnfs │
|
│ gateway │ │ static │ │ dnfs │ │ db │ │ ai_review │
|
||||||
│ 应用层网关 │ │ 前端托管服务 │ │ 树状菜单服务 │
|
│ 应用层网关 │ │ 前端托管服务 │ │树状菜单│ │ 通用数据库 │ │ AI内容审核 │
|
||||||
│ :9201 (入口) │ │ :9200 │ │ :8006 │
|
│ :443 (入口) │ │ :9200 │ │ :8006 │ │ :8005 │ │ :8007 │
|
||||||
│ 鉴权 + 反代 │ │ 静态/媒体文件 │ │ 节点树 CRUD │
|
│ 鉴权 + 反代 │ │ 静态/媒体 │ │节点CRUD│ │ SQL-over-HTTP│ │ DeepSeek+RAG │
|
||||||
└────────┬───────┘ └────────────────┘ └────────────────┘
|
└──────┬───────┘ └──────────────┘ └───┬────┘ └──────────────┘ └──────────────┘
|
||||||
│ 反向代理
|
│ 反向代理 │ 调用
|
||||||
┌────────┴────────┐
|
├────────────────► static:9200 ├──────────► db:8005
|
||||||
▼ ▼
|
└────────────────► dnfs:8006 └──────────► ai_review:8007
|
||||||
static:9200 dnfs:8006
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 请求链路
|
### 请求链路
|
||||||
|
|
||||||
1. 客户端所有请求统一打到 `gateway:9201`。
|
1. 客户端所有请求统一打到 `gateway:443`（HTTPS）。
|
||||||
2. `gateway` 对 `/login`、`/register` 做账号鉴权（SQLite + SHA256 + RSA 签名 Token）。
|
2. `gateway` 对 `/login`、`/register` 做账号鉴权（SQLite + SHA256 + RSA 签名 Token）。
|
||||||
3. 其余请求携带 Token，经 `gateway` 校验后反向代理到 `Proxy.opened` 中放开的内部服务（`static:9200` / `dnfs:8006`）。
|
3. 其余请求携带 Token，经 `gateway` 校验后反向代理到 `Proxy.opened` 中放开的内部服务（`static:9200` / `dnfs:8006`）。
|
||||||
4. `static` 提供前端页面与媒体流播放，`dnfs` 提供树状节点的增删改查。
|
4. `db:8005` 与 `ai_review:8007` 在 `Proxy.closed` 中，仅允许内部服务间调用，不对外暴露。
|
||||||
|
5. `dnfs` 处理节点增删改查时，通过 HTTP 调用 `db` 服务完成数据持久化，新增节点前调用 `ai_review` 进行内容审核。
|
||||||
|
|
||||||
## 各服务说明
|
## 各服务说明
|
||||||
|
|
||||||
| 服务 | 语言 | 端口 | 职责 |
|
| 服务 | 语言 | 端口 | 职责 |
|
||||||
|------|------|------|------|
|
|------|------|------|------|
|
||||||
| [core](core/) | C++20 | 5200 | 进程托管服务（PMC），创建/列举/杀死/执行子进程，读取自启动列表守护业务进程，提供 HTTP 管理接口 |
|
| [core](core/) | C++20 | 5200 | 进程托管服务（PMC），创建/列举/杀死/执行子进程，读取自启动列表守护业务进程，提供 HTTP 管理接口 |
|
||||||
| [gateway](gateway/) | C++20 | 9201 | 应用层网关（入口），用户注册/登录鉴权、Token 签发与校验、反向代理到内部服务 |
|
| [gateway](gateway/) | C++20 | 443 | 应用层网关（入口），用户注册/登录鉴权、Token 签发与校验、反向代理到内部服务 |
|
||||||
| [static](static/) | Python(Flask) | 9200 | 前端托管服务，静态页面与文件浏览、视频/音频流媒体播放、路径遍历防护 |
|
| [static](static/) | Python(Flask) | 9200 | 前端托管服务，社区首页、静态页面与文件浏览、视频/音频流媒体播放、路径遍历防护 |
|
||||||
| [dnfs](dnfs/) | Python(Flask) | 8006 | 树状网络文件系统（Dendrachy Network File-System），基于父子 pid 的节点树增删改查 |
|
| [dnfs](dnfs/) | Python(Flask) | 8006 | 树状网络文件系统（Dendrachy Network File-System），基于父子 pid 的节点树增删改查，集成 AI 内容审核 |
|
||||||
|
| [db](db/) | Python(Flask) | 8005 | 通用数据库服务，基于 SQLAlchemy Core 的 SQL-over-HTTP，支持 select/insert/update/delete，参数化查询防注入 |
|
||||||
|
| [ai_review](ai_review/) | Python(Flask) | 8007 | AI 内容审核服务，DeepSeek LLM + ChromaDB RAG，支持人工反馈纠偏 |
|
||||||
|
|
||||||
### core（核心模块 · 进程托管服务）
|
### core（核心模块 · 进程托管服务）
|
||||||
|
|
||||||
- 可执行文件 `nidus.out`，作为 systemd 服务（`Nidus.service`）常驻运行。
|
- 可执行文件 `nidus.out`，作为 systemd 服务（`Nidus.service`）常驻运行。
|
||||||
- 支持两种工作模式：命令行子系统调用（`--send/--exec/--list/--kill`）与 HTTP 伺服器模式（`--serve <port>`）。
|
- 支持两种工作模式：命令行子系统调用（`--send/--exec/--list/--kill`）与 HTTP 伺服器模式（`--serve <port>`）。
|
||||||
- 通过命名管道（Pipe）与消息队列（Mq）实现进程间通信。
|
- 通过命名管道（Pipe）与消息队列（Mq）实现进程间通信。
|
||||||
- 读取 `init.txt` 自启动列表，按行拉起各业务服务（static / dnfs / gateway）。
|
- 读取 `init.txt` 自启动列表，按行拉起各业务服务（ai_review / db / dnfs / static / gateway）。
|
||||||
|
|
||||||
### gateway（应用层网关）
|
### gateway（应用层网关）
|
||||||
|
|
||||||
- 唯一对外入口，承载 HTTPS（`full_chain.crt` / `server.key`）。
|
- 唯一对外入口，承载 HTTPS（`full_chain.crt` / `server.key`），默认监听 443 端口。
|
||||||
- 用户表 `Users`（email + SHA256 密码哈希），登录成功后用 RSA 私钥签发 `Base64(payload)_signature` 形式的 Token。
|
- 用户表 `Users`（email + SHA256 密码哈希），登录成功后用 RSA 私钥签发 `Base64(payload)_signature` 形式的 Token。
|
||||||
- 反向代理时校验 Token 签名与过期时间，仅放行 `Proxy.opened` 中配置的内部地址。
|
- 反向代理时校验 Token 签名与过期时间，仅放行 `Proxy.opened` 中配置的内部地址。
|
||||||
|
- `Proxy.closed` 配置内部专用服务（db:8005 / ai_review:8007），禁止外部直接访问。
|
||||||
- 配置示例见 [gateway/example.ini](gateway/example.ini)。
|
- 配置示例见 [gateway/example.ini](gateway/example.ini)。
|
||||||
|
|
||||||
### static（前端托管服务）
|
### static（前端托管服务）
|
||||||
|
|
||||||
- 托管 `public/` 下的前端页面（`login.html` / `register.html` / `dnfs.html` 等）。
|
- 托管 `public/` 下的前端页面：社区首页（`index.html`）、登录/注册、树状笔记（`dnfs.html`）、文件浏览（`__view.html`）等。
|
||||||
- 支持文件浏览、视频/音频在线播放（HTTP Range 分段请求）、一键下载。
|
- 支持文件浏览、视频/音频在线播放（HTTP Range 分段请求）、一键下载。
|
||||||
- 路径遍历防护，仅允许访问 `directory.root` 之内。
|
- 路径遍历防护，仅允许访问 `directory.root` 之内。
|
||||||
|
- 统一品牌"树状菜单"，支持深色模式（`css/theme.css`）。
|
||||||
|
- 可使用 Nuitka 编译为独立二进制（`fsys.bin`）。
|
||||||
- 配置见 [static/config.ini](static/config.ini)。
|
- 配置见 [static/config.ini](static/config.ini)。
|
||||||
|
|
||||||
### dnfs（树状菜单服务）
|
### dnfs（树状菜单服务）
|
||||||
|
|
||||||
- 基于 `pid`（父节点 id）组织的树状节点，节点含 `title` 与 `content`。
|
- 基于 `pid`（父节点 id）组织的树状节点，节点含 `title` 与 `content`。
|
||||||
- 提供 `/get_notes`、`/add_note`、`/delete_note`、`/update_note` 四个接口。
|
- 提供 `/get_notes`、`/add_note`、`/delete_note`、`/update_note` 四个接口。
|
||||||
- 数据持久化于 `notes.db`（SQLite + SQLAlchemy）。
|
- 数据持久化通过 HTTP 调用 `db` 服务（`http://127.0.0.1:8005/execute`），不再直接操作数据库。
|
||||||
|
- 新增节点前调用 `ai_review` 服务（`http://127.0.0.1:8007/review`）进行内容审核，审核不通过则拒绝写入。
|
||||||
|
|
||||||
|
### db（通用数据库服务）
|
||||||
|
|
||||||
|
- 单一接口 `POST /execute`，接收结构化 JSON（action + table + where + values），翻译为 SQL 执行。
|
||||||
|
- 支持 select / insert / update / delete，运算符包括 eq、ne、gt、lt、ge、le、like、in，支持排序与分页。
|
||||||
|
- 基于 SQLAlchemy Core 表反射，参数化查询，零 SQL 注入风险。
|
||||||
|
- 仅监听 127.0.0.1，单线程，自动回滚，不暴露 DDL 操作。
|
||||||
|
- 默认使用 SQLite（`database.db`），可通过 `DATABASE_URL` 环境变量切换至 PostgreSQL / MySQL。
|
||||||
|
|
||||||
|
### ai_review（AI 内容审核服务）
|
||||||
|
|
||||||
|
- 基于 DeepSeek LLM + ChromaDB 向量检索的 RAG 审核架构。
|
||||||
|
- 审核类别：色情、违禁药品、赌博、诈骗、仇恨/暴力/恐怖主义，灰色地带内容从严判定。
|
||||||
|
- 接口：`POST /review`（提交审核）、`POST /rag/feedback`（人工纠偏）、`GET /rag/list`（知识库列表）、`GET /health`（健康检查）。
|
||||||
|
- RAG 检索 top-3 相似已标注样本注入 prompt，MD5 去重，API 异常时 fail-open。
|
||||||
|
- 配置通过 `.env` 文件（已 gitignore），含 DeepSeek API 密钥、模型参数、监听地址。
|
||||||
|
|
||||||
## 共享基础库
|
## 共享基础库
|
||||||
|
|
||||||
@@ -76,22 +98,33 @@
|
|||||||
| [libth](libth/) | 线程库：`Thread`、`Cv_wait`（条件变量等待）、`Fsm`、`ITask` 任务接口 |
|
| [libth](libth/) | 线程库：`Thread`、`Cv_wait`（条件变量等待）、`Fsm`、`ITask` 任务接口 |
|
||||||
| [libhttp](libhttp/) | HTTP/WebSocket 库：`HttpServer`、`HttpClient`、`WebSocketServer/Client`（基于 Boost.Beast） |
|
| [libhttp](libhttp/) | HTTP/WebSocket 库：`HttpServer`、`HttpClient`、`WebSocketServer/Client`（基于 Boost.Beast） |
|
||||||
| [libcrypt](libcrypt/) | 加密库：`AES_CBC`、`MyRSA`、`SHA256`、`Base64`、`Crypto_Basic` |
|
| [libcrypt](libcrypt/) | 加密库：`AES_CBC`、`MyRSA`、`SHA256`、`Base64`、`Crypto_Basic` |
|
||||||
| [libsqlite3](libsqlite3/) | SQLite3 C++ 封装 |
|
| [libsqlite3](libsqlite3/) | SQLite3 C++ 封装（Header-only） |
|
||||||
|
|
||||||
|
## 端口一览
|
||||||
|
|
||||||
|
| 端口 | 服务 | 绑定地址 | 说明 |
|
||||||
|
|------|------|----------|------|
|
||||||
|
| 443 | gateway | 0.0.0.0 | HTTPS 对外入口 |
|
||||||
|
| 5200 | core | — | PMC HTTP 管理接口 |
|
||||||
|
| 9200 | static | 127.0.0.1 | 前端托管（经 gateway 代理） |
|
||||||
|
| 8006 | dnfs | 127.0.0.1 | 树状菜单（经 gateway 代理） |
|
||||||
|
| 8005 | db | 127.0.0.1 | 数据库服务（仅内部调用） |
|
||||||
|
| 8007 | ai_review | 127.0.0.1 | AI 审核（仅内部调用） |
|
||||||
|
|
||||||
## 依赖
|
## 依赖
|
||||||
|
|
||||||
- **系统级**：`g++`（C++20）、`make`、`libboost-all-dev`、`libcurl4-gnutls-dev`、`libssl-dev`、`libsqlite3-dev`、`python3`、`python3-venv`、`patchelf`
|
- **系统级**：`g++`（C++20）、`make`、`libboost-all-dev`、`libcurl4-gnutls-dev`、`libssl-dev`、`libsqlite3-dev`、`python3`、`python3-venv`、`python3-pip`、`patchelf`
|
||||||
- **Python**：Flask、Flask-CORS、Flask-SQLAlchemy、waitress（详见各服务 `requirements.txt`）
|
- **Python**：Flask、Flask-CORS、Flask-SQLAlchemy、SQLAlchemy、waitress、openai、chromadb、python-dotenv、nuitka（详见各服务 `requirements.txt`）
|
||||||
|
|
||||||
## 安装
|
## 安装
|
||||||
|
|
||||||
根目录提供一键安装脚本，按依赖顺序依次构建并安装各模块（库先行，core 最后）：
|
根目录提供一键安装脚本，按依赖顺序依次构建并安装各模块（库先行，core 最后）：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 安装系统依赖
|
# 1. 安装系统依赖（Debian/Ubuntu）
|
||||||
bash _setup.sh
|
bash _setup.deb.sh
|
||||||
|
|
||||||
# 2. 依次安装各模块（libth -> libhttp -> libcrypt -> gateway -> static -> dnfs -> core）
|
# 2. 依次安装各模块（libth -> libhttp -> libcrypt -> libsqlite3 -> gateway -> static -> dnfs -> db -> core）
|
||||||
bash _inst.sh
|
bash _inst.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -104,13 +137,17 @@ bash _run.sh # 运行
|
|||||||
|
|
||||||
部署路径约定为 `/opt/micro_servers/`，`core` 的 `init.txt` 即从该路径拉起其余服务。
|
部署路径约定为 `/opt/micro_servers/`，`core` 的 `init.txt` 即从该路径拉起其余服务。
|
||||||
|
|
||||||
|
> **注意**：`ai_review` 未包含在 `_inst.sh` 中，需单独进入 `ai_review/` 目录执行 `_set.sh` 安装，并配置 `.env` 文件（DeepSeek API 密钥等）。
|
||||||
|
|
||||||
## 运行
|
## 运行
|
||||||
|
|
||||||
由 `core` 守护的子进程通过 `init.txt` 自启动：
|
由 `core` 守护的子进程通过 `init.txt` 自启动：
|
||||||
|
|
||||||
```
|
```
|
||||||
bash /opt/micro_servers/static/_run.sh
|
bash /opt/micro_servers/ai_review/_run.sh
|
||||||
|
bash /opt/micro_servers/db/_run.sh
|
||||||
bash /opt/micro_servers/dnfs/_run.sh
|
bash /opt/micro_servers/dnfs/_run.sh
|
||||||
|
bash /opt/micro_servers/static/_run.sh
|
||||||
bash /opt/micro_servers/gateway/_run.sh
|
bash /opt/micro_servers/gateway/_run.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -120,16 +157,18 @@ bash /opt/micro_servers/gateway/_run.sh
|
|||||||
systemctl start Nidus # 或 bash core/_run.sh
|
systemctl start Nidus # 或 bash core/_run.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
对外访问入口：`https://<host>:9201`。
|
对外访问入口：`https://<host>:443`。
|
||||||
|
|
||||||
## 关于架构定位
|
## 关于架构定位
|
||||||
|
|
||||||
本项目具备微服务架构的核心特征，是一种**进程托管式轻量微服务**：
|
本项目具备微服务架构的核心特征，是一种**进程托管式轻量微服务**：
|
||||||
|
|
||||||
- **服务按业务能力拆分**：网关、前端托管、节点树各自独立、独立端口、独立数据存储。
|
- **服务按业务能力拆分**：网关、前端托管、节点树、数据库、内容审核各自独立、独立端口、独立数据存储。
|
||||||
- **API 网关模式**：`gateway` 统一入口，承担鉴权与反向代理。
|
- **API 网关模式**：`gateway` 统一入口，承担鉴权与反向代理，内部服务通过 `closed` 列表隔离。
|
||||||
- **进程编排/守护**：`core` 作为服务管理器拉起并守护子进程，类似简易版 supervisor。
|
- **进程编排/守护**：`core` 作为服务管理器拉起并守护子进程，类似简易版 supervisor。
|
||||||
- **多语言异构**：C++（core / gateway）与 Python（static / dnfs）混合，通过 HTTP 通信。
|
- **多语言异构**：C++（core / gateway）与 Python（static / dnfs / db / ai_review）混合，通过 HTTP 通信。
|
||||||
|
- **数据访问层解耦**：`db` 服务将数据库操作收敛为统一的 HTTP 接口，业务服务无需直连数据库。
|
||||||
|
- **AI 能力集成**：`ai_review` 以 RAG 增强的 LLM 审核为业务层提供内容安全能力，支持人工反馈闭环。
|
||||||
|
|
||||||
与云原生微服务的差异：未引入服务注册发现、容器编排、消息总线，服务地址在 `gateway/example.ini` 中静态配置。对于个人/中小规模的 DIY 场景，这种取舍在简洁性与可控性上是合理的。
|
与云原生微服务的差异：未引入服务注册发现、容器编排、消息总线，服务地址在 `gateway/example.ini` 中静态配置。对于个人/中小规模的 DIY 场景，这种取舍在简洁性与可控性上是合理的。
|
||||||
|
|
||||||
|
|||||||
+196
-13
@@ -1,18 +1,201 @@
|
|||||||
|
# DNFS — 树状网络文件系统
|
||||||
|
|
||||||
# DNFS
|
Dendrachy Network File-System，基于父子关系（pid）组织的树状节点服务。
|
||||||
|
|
||||||
这个项目叫做**树状网络文件系统（DNFS）**，是个HTTP服务。
|
监听 `127.0.0.1:8006`，提供节点的增删改查，支持文件以 Base64 编码形式存储在节点 content 中。
|
||||||
|
|
||||||
它监听本地**8006**端口，访问者可以枚举、添加、删除、更新节点。
|
## 架构
|
||||||
|
|
||||||
# 接口
|
|
||||||
```bash
|
|
||||||
# 获取某一层的节点列表
|
|
||||||
curl -X POST http://localhost:8006/get_notes -d '{"pid": <integer>}'
|
|
||||||
# 添加一个节点
|
|
||||||
curl -X POST http://localhost:8006/add_note -d '{"pid": <int>, "title": <str>, "content": <str>}'
|
|
||||||
# 删除一个节点
|
|
||||||
curl -X POST http://localhost:8006/delete_note -d '{"id": <int>}'
|
|
||||||
# 更新一个节点
|
|
||||||
curl -X POST http://localhost:8006/update_note -d '{"id": <int>, "pid": <int>, "title": <str>, "content": <str>}'
|
|
||||||
```
|
```
|
||||||
|
客户端 (static/dnfs.html)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
dnfs :8006 (Flask + Waitress)
|
||||||
|
│
|
||||||
|
├──► db :8005 数据持久化（SQL-over-HTTP）
|
||||||
|
└──► ai_review :8007 内容审核（仅 add_note 时调用）
|
||||||
|
```
|
||||||
|
|
||||||
|
dnfs 不再直连数据库，所有数据操作通过 HTTP 调用 `db` 服务（`http://127.0.0.1:8005/execute`）完成。新增节点前会调用 `ai_review` 服务（`http://127.0.0.1:8007/review`）进行内容审核，审核不通过则拒绝写入。
|
||||||
|
|
||||||
|
## 接口文档
|
||||||
|
|
||||||
|
所有接口均为 `POST`，Content-Type 为 `application/json`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### POST /get_notes
|
||||||
|
|
||||||
|
获取指定父节点下的子节点列表。
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| pid | int | 否 | 父节点 id，0 表示根节点，缺省默认 0 |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8006/get_notes \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-d '{"pid": 0}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 200**
|
||||||
|
|
||||||
|
直接返回节点数组：
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{"id": 1, "pid": 0, "title": "根节点", "content": "hello"},
|
||||||
|
{"id": 2, "pid": 0, "title": "另一个", "content": "world"}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| id | int | 节点唯一标识 |
|
||||||
|
| pid | int | 父节点 id |
|
||||||
|
| title | str | 节点标题 |
|
||||||
|
| content | str | 节点内容（可能含 Base64 文件数据） |
|
||||||
|
|
||||||
|
空目录返回 `[]`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### POST /add_note
|
||||||
|
|
||||||
|
添加新节点。流程：校验参数 → 校验父节点存在 → AI 内容审核 → 写入数据库。
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| pid | int | 是 | 父节点 id，0 为根节点，非 0 时校验父节点是否存在 |
|
||||||
|
| title | str | 是 | 节点标题，不可为空 |
|
||||||
|
| content | str | 是 | 节点内容，不可为空（可含 Base64 文件数据） |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8006/add_note \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-d '{"pid": 0, "title": "新节点", "content": "节点内容"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 200** — 成功
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"success": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 400** — 失败
|
||||||
|
|
||||||
|
| 场景 | 响应体 |
|
||||||
|
|------|--------|
|
||||||
|
| 缺少必填字段 | `{"error": "Pid, title and content are required"}` |
|
||||||
|
| 父节点不存在（pid≠0） | `{"error": "the new node need a parent"}` |
|
||||||
|
| AI 内容审核不通过 | `{"error": "review failed"}` |
|
||||||
|
| 数据库写入失败 | `{"success": false}` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### POST /delete_note
|
||||||
|
|
||||||
|
删除指定节点。存在子节点时拒绝删除（保护树结构完整性）。
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| id | int | 是 | 要删除的节点 id |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8006/delete_note \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-d '{"id": 1}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 200** — 成功
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"success": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 400** — 失败
|
||||||
|
|
||||||
|
| 场景 | 响应体 |
|
||||||
|
|------|--------|
|
||||||
|
| 缺少 id 字段 | `{"error": "Note ID is required"}` |
|
||||||
|
| 存在子节点 | `{"error": "this node has a child"}` |
|
||||||
|
| 数据库删除失败 | `{"success": false}` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### POST /update_note
|
||||||
|
|
||||||
|
更新节点的标题、内容和父节点（可用于迁移节点到其他位置）。
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| id | int | 是 | 要更新的节点 id |
|
||||||
|
| pid | int | 是 | 新的父节点 id（迁移时改变此值） |
|
||||||
|
| title | str | 是 | 新标题，不可为空 |
|
||||||
|
| content | str | 是 | 新内容，不可为空 |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8006/update_note \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-d '{"id": 1, "pid": 2, "title": "新标题", "content": "新内容"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 200** — 成功
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"success": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response 400** — 失败
|
||||||
|
|
||||||
|
| 场景 | 响应体 |
|
||||||
|
|------|--------|
|
||||||
|
| 缺少必填字段 | `{"error": "Invalid param"}` |
|
||||||
|
| 数据库更新失败 | `{"success": false}` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 前端
|
||||||
|
|
||||||
|
三文件架构：
|
||||||
|
|
||||||
|
```
|
||||||
|
templates/index.html 页面结构（Font Awesome 图标）
|
||||||
|
static/css/style.css 样式
|
||||||
|
static/js/script.js 交互逻辑
|
||||||
|
```
|
||||||
|
|
||||||
|
功能：节点树浏览、新增/编辑/删除节点、文件 Base64 上传与下载、节点迁移（移动到其他父节点下）。
|
||||||
|
|
||||||
|
> 注：首页路由 `@app.route('/')` 当前已注释，前端页面实际由 static 服务的 `dnfs.html` 承载。
|
||||||
|
|
||||||
|
## 依赖
|
||||||
|
|
||||||
|
```
|
||||||
|
flask
|
||||||
|
flask-cors
|
||||||
|
waitress
|
||||||
|
nuitka # 可选，编译为独立二进制
|
||||||
|
```
|
||||||
|
|
||||||
|
运行时需要 `db`（:8005）和 `ai_review`（:8007）服务已启动。
|
||||||
|
|
||||||
|
## 运行
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash _set.sh # 创建 venv + 安装依赖
|
||||||
|
bash _run.sh # 启动服务
|
||||||
|
```
|
||||||
|
|
||||||
|
## 已知问题
|
||||||
|
|
||||||
|
- `delete_note` 中子节点检查逻辑有误：查询条件为 `where id = note_id`（查节点自身），应为 `where pid = note_id`（查子节点），导致任何节点都无法删除。
|
||||||
|
- `review_content` 返回值类型不一致：正常返回 `bool`，HTTPError 时返回 `dict`。
|
||||||
+60
-80
@@ -1,34 +1,57 @@
|
|||||||
# 文件托管服务器
|
# static — 前端托管服务
|
||||||
|
|
||||||
一个基于 Flask 的轻量级文件托管与浏览服务器，支持视频/音频流媒体播放和文件下载。
|
基于 Flask 的轻量级文件托管与前端页面服务，监听 `127.0.0.1:9200`。
|
||||||
|
|
||||||
## ✨ 功能特性
|
承载"树状菜单"社区的全部前端页面，同时提供文件浏览与流媒体播放能力。
|
||||||
|
|
||||||
- **文件浏览** - 现代化 Web 界面，支持文件列表查看和目录导航
|
## 架构
|
||||||
- **流媒体支持** - 支持视频和音频文件的在线播放及拖动进度条
|
|
||||||
- **文件下载** - 一键下载任意文件
|
|
||||||
- **文件搜索** - 支持实时搜索过滤（快捷键：`/` 或 `Ctrl+F`）
|
|
||||||
- **响应式设计** - 同时支持桌面端和移动端访问
|
|
||||||
- **深色模式** - 自动适配系统深色/浅色主题
|
|
||||||
- **面包屑导航** - 快速定位当前目录位置
|
|
||||||
- **文件统计** - 实时显示目录中文件和子目录数量
|
|
||||||
|
|
||||||
## 🚀 快速开始
|
```
|
||||||
|
gateway :443 (反向代理)
|
||||||
### 安装依赖
|
│
|
||||||
|
▼
|
||||||
```bash
|
static :9200 (Flask + CORS)
|
||||||
pip install flask flask-cors
|
│
|
||||||
|
└── public/ 托管目录
|
||||||
|
├── index.html 社区首页
|
||||||
|
├── login.html 登录
|
||||||
|
├── register.html 注册
|
||||||
|
├── dnfs.html 树状笔记（调用 dnfs:8006）
|
||||||
|
├── __view.html 文件浏览器（系统文件，不在列表中显示）
|
||||||
|
├── allcolor.html 调色板
|
||||||
|
├── css/ theme.css（统一主题）+ view.css
|
||||||
|
├── js/ dnfs.js / login.js / register.js / validation.js / view.js
|
||||||
|
├── games/ HTML 小游戏合集
|
||||||
|
└── favicon.ico
|
||||||
```
|
```
|
||||||
|
|
||||||
### 配置文件
|
## 路由
|
||||||
|
|
||||||
创建 `config.ini` 配置文件（可选，不创建则使用默认配置）：
|
| 路径 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `GET /` | 社区首页（index.html），不存在时回退 `__view.html` |
|
||||||
|
| `GET /<path>` | 静态文件服务；目录返回 `__view.html` 由前端拉取列表 |
|
||||||
|
| `GET /api/filelist?path=` | 文件列表 API，过滤 `__` 前缀系统文件 |
|
||||||
|
| `GET /video/<path>` | 视频/音频流媒体（HTTP Range 206 分段） |
|
||||||
|
| `GET /<path>?download=true` | 强制下载 |
|
||||||
|
| `GET /health` | 健康检查 |
|
||||||
|
|
||||||
|
## 功能
|
||||||
|
|
||||||
|
- 文件浏览：目录导航、面包屑、实时搜索（`/` 或 `Ctrl+F`）、文件统计
|
||||||
|
- 流媒体：视频（MP4/WebM/OGG/AVI/MOV/MKV）与音频（MP3/WAV/OGG/FLAC/AAC/M4A）在线播放，支持进度拖动
|
||||||
|
- 深色模式：`css/theme.css` 统一主题，自动适配系统偏好
|
||||||
|
- 路径遍历防护：`safe_path_join` 限制访问范围在 `directory.root` 内
|
||||||
|
- Nuitka 编译：可打包为独立二进制 `fsys.bin`（`sys.frozen` 检测 + BASE_DIR 锚定）
|
||||||
|
|
||||||
|
## 配置
|
||||||
|
|
||||||
|
`config.ini`：
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
[server]
|
[server]
|
||||||
host = 0.0.0.0
|
host = 127.0.0.1
|
||||||
port = 5000
|
port = 9200
|
||||||
|
|
||||||
[directory]
|
[directory]
|
||||||
root = ./public
|
root = ./public
|
||||||
@@ -39,70 +62,27 @@ cert_file = cert.pem
|
|||||||
key_file = key.pem
|
key_file = key.pem
|
||||||
```
|
```
|
||||||
|
|
||||||
### 启动服务器
|
## 依赖
|
||||||
|
|
||||||
|
```
|
||||||
|
flask>=2.3.0,<3.0.0
|
||||||
|
flask-cors>=4.0.0,<5.0.0
|
||||||
|
nuitka # 可选，编译为独立二进制
|
||||||
|
```
|
||||||
|
|
||||||
|
## 运行
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python file_server.py
|
bash _set.sh # 创建 venv + 安装依赖
|
||||||
|
bash _run.sh # 启动服务（当前使用 python3，Nuitka 二进制已注释）
|
||||||
```
|
```
|
||||||
|
|
||||||
或指定配置文件：
|
## 备注
|
||||||
|
|
||||||
```bash
|
- 以 `__` 开头的文件/目录（`__view.html`、`__icons/`）为系统内部使用，文件列表 API 中不显示。
|
||||||
python file_server.py --config my_config.ini
|
- ICP 备案：蜀ICP备2024107064号-2，链接至 beian.miit.gov.cn，已置于 index/login/register/dnfs 四页 footer。
|
||||||
```
|
- 入口文件名为 `fsys.py`（旧 README 中的 `file_server.py` 已废弃）。
|
||||||
|
|
||||||
服务器启动后，访问 `http://localhost:5000` 即可浏览文件。
|
## 许可证
|
||||||
|
|
||||||
## 📁 目录结构
|
|
||||||
|
|
||||||
将需要托管的文件放入配置的目录（默认为 `./public`），服务器会自动创建该目录。
|
|
||||||
|
|
||||||
```
|
|
||||||
project/
|
|
||||||
├── file_server.py # 主程序
|
|
||||||
├── config.ini # 配置文件（可选）
|
|
||||||
└── public/ # 托管文件目录（自动创建）
|
|
||||||
├── videos/
|
|
||||||
├── music/
|
|
||||||
└── documents/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎬 支持的媒体格式
|
|
||||||
|
|
||||||
| 类型 | 支持的格式 |
|
|
||||||
|------|-----------|
|
|
||||||
| 视频 | MP4, WebM, OGG, AVI, MOV, MKV |
|
|
||||||
| 音频 | MP3, WAV, OGG, FLAC, AAC, M4A |
|
|
||||||
|
|
||||||
## 📡 API 接口
|
|
||||||
|
|
||||||
### 获取文件列表
|
|
||||||
```
|
|
||||||
GET /api/filelist?path=subdir
|
|
||||||
```
|
|
||||||
|
|
||||||
### 流媒体播放
|
|
||||||
```
|
|
||||||
GET /video/{filepath}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 健康检查
|
|
||||||
```
|
|
||||||
GET /health
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔒 安全特性
|
|
||||||
|
|
||||||
- 路径遍历防护，防止访问托管目录外的文件
|
|
||||||
- 完善的错误处理和日志记录
|
|
||||||
- 支持 HTTPS/SSL 加密传输
|
|
||||||
|
|
||||||
## 📋 依赖
|
|
||||||
|
|
||||||
- Python 3.6+
|
|
||||||
- Flask
|
|
||||||
- Flask-CORS
|
|
||||||
|
|
||||||
## 📄 许可证
|
|
||||||
|
|
||||||
MIT License
|
MIT License
|
||||||
Reference in new issue
Block a user