Update README.md

README.md

@@ -1,715 +1,701 @@
----
-title: PostgreSQL General
-emoji: 🏃
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-pinned: false
----
+## 14. 用户账号机制说明
 
-# PostgreSQL Adminer on Hugging Face Space
+本项目不提供公开注册功能。
 
-这是一个用于在 Hugging Face Docker Space 上部署 PostgreSQL 数据库与 Adminer 管理界面的项目。
+PostgreSQL 用户账号不是网站账号，也不是任何人都可以自助注册的账号。所有数据库用户、数据库、schema 和权限都必须由管理员通过 Adminer 或 SQL 命令手动创建。
 
-本项目采用以下设计：
+默认初始化管理员账号由以下环境变量决定：
 
-```text
-PostgreSQL 程序：运行在 Hugging Face Space 容器内
-PostgreSQL 数据目录：使用 Space 本地磁盘 /home/user/pgdata
-挂载大磁盘 /data：用于保存备份、用户文件、导出文件和生成文件
-Adminer Web 管理界面：通过 7860 端口访问
+```env
+POSTGRES_USER=admin
+POSTGRES_PASSWORD=your_strong_password
+POSTGRES_DB=appdb
 ```
 
-不建议把 PostgreSQL 的运行数据目录直接放到挂载磁盘 `/data/postgres`，因为 PostgreSQL 对底层文件系统权限、锁、随机读写、WAL、fsync 等要求较高。挂载磁盘更适合保存备份文件和业务文件。
+默认管理员：
 
----
-
-## 1. 项目结构
+```text
+Username: admin
+Database: appdb
+Password: POSTGRES_PASSWORD
+```
 
-仓库根目录包含以下文件：
+`admin` 是数据库管理员账号，拥有较高权限，主要用于：
 
 ```text
-README.md
-Dockerfile
-start.sh
+1. 登录 Adminer
+2. 创建数据库
+3. 创建项目用户
+4. 分配数据库权限
+5. 查看和维护数据库
+6. 执行备份、恢复、迁移等管理操作
 ```
 
----
+不建议把 `admin` 账号直接提供给外部项目或普通用户使用。
 
-## 2. 整体架构
+---
 
-```text
-浏览器
-  ↓
-Hugging Face Space Web 入口，端口 7860
-  ↓
-Adminer 管理界面
-  ↓
-PostgreSQL，容器内部 5432 端口
-```
+## 15. 管理员如何创建项目数据库和账号
 
-目录设计：
+推荐原则：
 
 ```text
-/home/user/pgdata
-  └── PostgreSQL 正在运行的数据库文件
-
-/data
-  ├── backups
-  │   ├── latest.sql
-  │   └── backup_appdb_YYYYMMDD_HHMMSS.sql
-  ├── files
-  │   └── 用户上传文件
-  ├── exports
-  │   └── 导出的 CSV / JSON / SQL 文件
-  └── generated
-      └── AI 生成文件、图片、视频等
+一个项目一个 database
+一个项目一个 user
+一个项目一个 password
 ```
 
-数据库中建议只保存文件路径、文件名、文件大小、MIME 类型等索引信息，不建议把大文件直接写入 PostgreSQL。
+例如，管理员要为 RSS 项目创建独立数据库和账号，可以登录 Adminer 后执行以下 SQL：
 
----
+```sql
+CREATE DATABASE rss_project;
+CREATE USER rss_user WITH PASSWORD 'replace_with_strong_password';
+GRANT ALL PRIVILEGES ON DATABASE rss_project TO rss_user;
+```
 
-## 3. Dockerfile
+然后切换到 `rss_project` 数据库，继续执行 schema 权限配置：
 
-```dockerfile
-FROM postgres:17
+```sql
+GRANT ALL ON SCHEMA public TO rss_user;
 
-ENV POSTGRES_USER=admin
-ENV POSTGRES_DB=appdb
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT ALL ON TABLES TO rss_user;
 
-# PostgreSQL 运行中的数据库目录：使用 Space 本地磁盘
-ENV PGDATA=/home/user/pgdata
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT ALL ON SEQUENCES TO rss_user;
 
-# 挂载大磁盘目录：用于备份、用户文件、导出文件
-ENV DATA_DIR=/data
-ENV BACKUP_DIR=/data/backups
-ENV USER_FILE_DIR=/data/files
-ENV EXPORT_DIR=/data/exports
-ENV GENERATED_DIR=/data/generated
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT ALL ON FUNCTIONS TO rss_user;
+```
 
-# 自动备份间隔，默认 1 小时
-ENV BACKUP_INTERVAL_SECONDS=3600
+完整示例：
 
-# Adminer 版本
-ENV ADMINER_VERSION=4.8.1
+```sql
+CREATE DATABASE image_project;
+CREATE USER image_user WITH PASSWORD 'image_project_strong_password';
+GRANT ALL PRIVILEGES ON DATABASE image_project TO image_user;
 
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    curl \
-    php \
-    php-pgsql \
-    ca-certificates \
-    procps \
-    && rm -rf /var/lib/apt/lists/*
+\c image_project
 
-RUN curl -L -o /adminer.php \
-    https://github.com/vrana/adminer/releases/download/v${ADMINER_VERSION}/adminer-${ADMINER_VERSION}.php
+GRANT ALL ON SCHEMA public TO image_user;
 
-COPY start.sh /start.sh
-RUN chmod +x /start.sh
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT ALL ON TABLES TO image_user;
 
-EXPOSE 5432
-EXPOSE 7860
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT ALL ON SEQUENCES TO image_user;
 
-CMD ["/start.sh"]
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT ALL ON FUNCTIONS TO image_user;
 ```
 
----
-
-## 4. start.sh
+创建完成后，业务项目可以使用以下连接格式：
 
-```bash
-#!/usr/bin/env bash
-set -e
-
-echo "======================================"
-echo "PostgreSQL + Adminer for Hugging Face"
-echo "======================================"
-
-if [ -z "$POSTGRES_PASSWORD" ]; then
-  echo "ERROR: POSTGRES_PASSWORD is not set."
-  echo "Please set POSTGRES_PASSWORD in Hugging Face Space Secrets."
-  exit 1
-fi
-
-export POSTGRES_USER="${POSTGRES_USER:-admin}"
-export POSTGRES_DB="${POSTGRES_DB:-appdb}"
-export PGDATA="${PGDATA:-/home/user/pgdata}"
-
-export DATA_DIR="${DATA_DIR:-/data}"
-export BACKUP_DIR="${BACKUP_DIR:-/data/backups}"
-export USER_FILE_DIR="${USER_FILE_DIR:-/data/files}"
-export EXPORT_DIR="${EXPORT_DIR:-/data/exports}"
-export GENERATED_DIR="${GENERATED_DIR:-/data/generated}"
-export BACKUP_INTERVAL_SECONDS="${BACKUP_INTERVAL_SECONDS:-3600}"
-
-echo "POSTGRES_USER=$POSTGRES_USER"
-echo "POSTGRES_DB=$POSTGRES_DB"
-echo "PGDATA=$PGDATA"
-echo "DATA_DIR=$DATA_DIR"
-echo "BACKUP_DIR=$BACKUP_DIR"
-echo "USER_FILE_DIR=$USER_FILE_DIR"
-echo "EXPORT_DIR=$EXPORT_DIR"
-echo "GENERATED_DIR=$GENERATED_DIR"
-echo "BACKUP_INTERVAL_SECONDS=$BACKUP_INTERVAL_SECONDS"
-
-echo "Creating directories..."
-
-mkdir -p "$PGDATA"
-mkdir -p "$BACKUP_DIR"
-mkdir -p "$USER_FILE_DIR"
-mkdir -p "$EXPORT_DIR"
-mkdir -p "$GENERATED_DIR"
-
-# PostgreSQL 数据目录需要 postgres 用户权限
-chown -R postgres:postgres "$PGDATA" || true
-chmod 700 "$PGDATA" || true
-
-# /data 是挂载大磁盘，可能不支持 chown，所以这里允许失败
-chmod -R 755 "$DATA_DIR" || true
-
-echo "Directory status:"
-ls -ld "$PGDATA" || true
-ls -ld "$DATA_DIR" || true
-ls -ld "$BACKUP_DIR" || true
-ls -ld "$USER_FILE_DIR" || true
-ls -ld "$EXPORT_DIR" || true
-ls -ld "$GENERATED_DIR" || true
-
-RESTORE_BACKUP=0
-
-if [ ! -s "$PGDATA/PG_VERSION" ]; then
-  echo "No existing PostgreSQL data directory found."
-
-  if [ -f "$BACKUP_DIR/latest.sql" ]; then
-    echo "Backup file found: $BACKUP_DIR/latest.sql"
-    echo "Database will be restored after PostgreSQL initialization."
-    RESTORE_BACKUP=1
-  else
-    echo "No backup file found. A new database will be initialized."
-  fi
-else
-  echo "Existing PostgreSQL data directory found."
-fi
-
-echo "Starting PostgreSQL..."
-docker-entrypoint.sh postgres &
-
-POSTGRES_PID=$!
-
-echo "Waiting for PostgreSQL to become ready..."
-
-until pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; do
-  sleep 2
-done
-
-echo "PostgreSQL is ready."
-
-if [ "$RESTORE_BACKUP" = "1" ]; then
-  echo "Restoring database from $BACKUP_DIR/latest.sql ..."
-
-  psql \
-    -h 127.0.0.1 \
-    -U "$POSTGRES_USER" \
-    -d "$POSTGRES_DB" \
-    < "$BACKUP_DIR/latest.sql" || {
-      echo "WARNING: Restore failed. Please check backup file."
-    }
+```env
+DATABASE_URL=postgresql://image_user:image_project_strong_password@127.0.0.1:5432/image_project
+```
 
-  echo "Restore process finished."
-fi
+注意：`127.0.0.1:5432` 是容器内部地址，适用于同一个 Space 容器内的应用。如果外部项目需要访问数据库，不建议直接暴露 PostgreSQL 端口，推荐使用 API Gateway。
 
-create_backup() {
-  TIMESTAMP="$(date +%Y%m%d_%H%M%S)"
-  BACKUP_FILE="$BACKUP_DIR/backup_${POSTGRES_DB}_${TIMESTAMP}.sql"
-  LATEST_FILE="$BACKUP_DIR/latest.sql"
+---
 
-  echo "Creating backup: $BACKUP_FILE"
+## 16. 创建只读账号
 
-  pg_dump \
-    -h 127.0.0.1 \
-    -U "$POSTGRES_USER" \
-    -d "$POSTGRES_DB" \
-    > "$BACKUP_FILE.tmp"
+如果需要给某个用户或项目只读权限，可以创建只读用户。
 
-  mv "$BACKUP_FILE.tmp" "$BACKUP_FILE"
-  cp "$BACKUP_FILE" "$LATEST_FILE"
+示例：
 
-  echo "Backup saved:"
-  echo "- $BACKUP_FILE"
-  echo "- $LATEST_FILE"
-}
+```sql
+CREATE USER readonly_user WITH PASSWORD 'readonly_strong_password';
 
-backup_loop() {
-  echo "Backup loop started. Interval: ${BACKUP_INTERVAL_SECONDS}s"
+GRANT CONNECT ON DATABASE rss_project TO readonly_user;
+```
 
-  while true; do
-    sleep "$BACKUP_INTERVAL_SECONDS"
+切换到目标数据库：
 
-    if pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; then
-      create_backup || echo "WARNING: Backup failed."
-    else
-      echo "WARNING: PostgreSQL is not ready. Backup skipped."
-    fi
-  done
-}
+```sql
+\c rss_project
+```
 
-# 启动后先做一次备份，避免 latest.sql 长时间不存在
-if pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; then
-  create_backup || echo "WARNING: Initial backup failed."
-fi
+授予只读权限：
 
-backup_loop &
+```sql
+GRANT USAGE ON SCHEMA public TO readonly_user;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
 
-echo "Starting Adminer on port 7860..."
-echo "Adminer login:"
-echo "System: PostgreSQL"
-echo "Server: 127.0.0.1"
-echo "Username: $POSTGRES_USER"
-echo "Database: $POSTGRES_DB"
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT SELECT ON TABLES TO readonly_user;
+```
 
-php -S 0.0.0.0:7860 /adminer.php
+只读账号适合：
 
-wait "$POSTGRES_PID"
+```text
+1. 数据分析
+2. BI 看板
+3. 外部查询服务
+4. 临时审查
+5. 只读 API 服务
 ```
 
 ---
 
-## 5. Hugging Face Space 配置
+## 17. 修改用户密码
 
-创建 Hugging Face Space 时选择：
+管理员可以使用以下 SQL 修改用户密码：
 
-```text
-SDK: Docker
-Visibility: Public 或 Private
-Hardware: CPU Basic 即可
+```sql
+ALTER USER rss_user WITH PASSWORD 'new_strong_password';
 ```
 
-README 顶部需要包含：
+修改后，使用旧密码的应用需要同步更新环境变量。
 
-```yaml
----
-title: PostgreSQL Adminer
-emoji: 🐘
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-app_port: 7860
-pinned: false
 ---
-```
 
-其中：
+## 18. 删除用户和数据库
 
-| 配置               | 说明                               |
-| ---------------- | -------------------------------- |
-| `sdk: docker`    | 使用 Dockerfile 构建 Space           |
-| `app_port: 7860` | Hugging Face 对外暴露 Adminer Web 页面 |
-| `title`          | Space 显示名称                       |
-| `emoji`          | Space 图标                         |
+删除用户前，需要先确认该用户不再拥有数据库对象。
 
----
-
-## 6. 环境变量
-
-在 Hugging Face Space 的：
+删除用户：
 
-```text
-Settings → Variables and secrets
+```sql
+DROP USER rss_user;
 ```
 
-中配置环境变量。
-
-### 必填 Secret
+删除数据库：
 
-| 变量名                 | 类型     | 示例                     | 说明               |
-| ------------------- | ------ | ---------------------- | ---------------- |
-| `POSTGRES_PASSWORD` | Secret | `your_strong_password` | PostgreSQL 管理员密码 |
+```sql
+DROP DATABASE rss_project;
+```
 
-### 推荐 Variables
+如果用户拥有表、sequence、函数等对象，可以先在对应数据库内执行：
 
-| 变量名                       | 默认值                 | 说明                |
-| ------------------------- | ------------------- | ----------------- |
-| `POSTGRES_USER`           | `admin`             | PostgreSQL 管理员用户名 |
-| `POSTGRES_DB`             | `appdb`             | 默认数据库名称           |
-| `PGDATA`                  | `/home/user/pgdata` | PostgreSQL 运行数据目录 |
-| `DATA_DIR`                | `/data`             | 挂载大磁盘根目录          |
-| `BACKUP_DIR`              | `/data/backups`     | 数据库备份目录           |
-| `USER_FILE_DIR`           | `/data/files`       | 用户上传文件目录          |
-| `EXPORT_DIR`              | `/data/exports`     | 导出文件目录            |
-| `GENERATED_DIR`           | `/data/generated`   | AI 生成文件目录         |
-| `BACKUP_INTERVAL_SECONDS` | `3600`              | 自动备份间隔，单位为秒       |
+```sql
+REASSIGN OWNED BY rss_user TO admin;
+DROP OWNED BY rss_user;
+```
 
-示例：
+然后再删除用户：
 
-```env
-POSTGRES_USER=admin
-POSTGRES_DB=appdb
-PGDATA=/home/user/pgdata
-DATA_DIR=/data
-BACKUP_DIR=/data/backups
-USER_FILE_DIR=/data/files
-EXPORT_DIR=/data/exports
-GENERATED_DIR=/data/generated
-BACKUP_INTERVAL_SECONDS=3600
+```sql
+DROP USER rss_user;
 ```
 
-不要把 `POSTGRES_PASSWORD` 写进代码仓库或 README 的真实值中，应放入 Hugging Face Secret。
+危险操作请谨慎执行，建议先备份数据库。
 
 ---
 
-## 7. 挂载磁盘设置
+## 19. 不建议直接对外暴露 PostgreSQL 端口
 
-建议将 Hugging Face Storage Bucket 挂载到：
+本项目默认暴露给 Hugging Face Space 的 Web 端口是：
 
 ```text
-/data
+7860
 ```
 
-推荐配置：
+该端口用于访问 Adminer 或 API 服务。
+
+PostgreSQL 默认端口是：
 
 ```text
-Mount path: /data
-Access mode: Read & Write
-Bucket visibility: Private
+5432
 ```
 
-挂载磁盘 `/data` 用于保存：
+不建议将 `5432` 直接暴露给公网。原因包括：
 
 ```text
-/data/backups      数据库备份
-/data/files        用户上传文件
-/data/exports      导出文件
-/data/generated    AI 生成文件
+1. PostgreSQL 是数据库服务，不是公开 Web 服务
+2. 公网暴露 5432 容易被扫描和攻击
+3. 数据库长连接在 Hugging Face Space 场景下不稳定
+4. 权限泄露风险较高
+5. 不便于统一鉴权、限流、日志和审计
 ```
 
-不建议将 PostgreSQL 的 `PGDATA` 设置为 `/data/postgres`。
+推荐对外提供 API，而不是让外部项目直接连接数据库。
+
+推荐架构：
+
+```text
+外部项目 / 用户
+  ↓
+API Token 鉴权
+  ↓
+FastAPI / API Gateway
+  ↓
+PostgreSQL
+```
 
 ---
 
-## 8. Adminer 登录方式
+## 20. 对外提供 API 调用接口的推荐方式
 
-部署完成后，打开 Hugging Face Space 页面，会看到 Adminer 登录界面。
+如果需要让外部项目调用数据库，建议在当前 Space 中增加一个 FastAPI 服务。
 
-填写：
+推荐公开 API：
 
 ```text
-System: PostgreSQL
-Server: 127.0.0.1
-Username: admin
-Password: 你的 POSTGRES_PASSWORD
-Database: appdb
+POST /api/query       执行受控查询
+POST /api/insert      写入数据
+GET  /api/health      健康检查
+GET  /api/files       查询文件索引
+POST /api/files       创建文件索引
 ```
 
-如果你修改了环境变量，请使用自己的值：
+不建议开放任意 SQL 执行接口给普通用户。
+
+推荐做法是：
 
 ```text
-Username: POSTGRES_USER
-Database: POSTGRES_DB
+1. 管理员在 PostgreSQL 中创建项目数据库和项目用户
+2. 管理员在 Space Secrets 中配置项目数据库连接串
+3. FastAPI 使用项目账号连接数据库
+4. 外部项目通过 API Token 调用 FastAPI
+5. FastAPI 执行受控 SQL
+6. PostgreSQL 不直接暴露给公网
 ```
 
 ---
 
-## 9. 数据保存逻辑
+## 21. API 鉴权方式
 
-本项目采用“数据库索引 + 文件系统存储”的设计。
+推荐使用 API Token。
 
-不推荐把大文件直接写入 PostgreSQL，例如：
+在 Hugging Face Space 的 Secrets 中配置：
 
-```sql
-CREATE TABLE files (
-  id SERIAL PRIMARY KEY,
-  content BYTEA
-);
+```env
+API_TOKEN=replace_with_random_api_token
 ```
 
-推荐把文件保存到 `/data/files`，数据库中只保存文件路径：
+外部项目请求 API 时，在 Header 中携带：
 
-```sql
-CREATE TABLE files (
-  id SERIAL PRIMARY KEY,
-  user_id TEXT,
-  filename TEXT NOT NULL,
-  file_path TEXT NOT NULL,
-  file_size BIGINT,
-  mime_type TEXT,
-  created_at TIMESTAMP DEFAULT now()
-);
+```http
+Authorization: Bearer replace_with_random_api_token
 ```
 
-示例记录：
-
-```text
-filename: image_001.png
-file_path: /data/files/image_001.png
-file_size: 245891
-mime_type: image/png
-```
+服务端验证通过后才允许访问数据库。
 
 ---
 
-## 10. 自动备份机制
+## 22. FastAPI 示例：健康检查接口
 
-启动脚本会自动执行备份。
+如果需要增加 API 服务，可以在项目中新增 `api.py`。
 
-默认备份间隔：
+示例：
 
-```text
-3600 秒，即 1 小时
-```
+```python
+import os
+import psycopg2
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
 
-可以通过环境变量修改：
+app = FastAPI()
 
-```env
-BACKUP_INTERVAL_SECONDS=1800
-```
+API_TOKEN = os.environ.get("API_TOKEN")
+DATABASE_URL = os.environ.get(
+    "DATABASE_URL",
+    "postgresql://admin:password@127.0.0.1:5432/appdb"
+)
 
-备份文件保存到：
 
-```text
-/data/backups
-```
+def verify_token(authorization: str | None):
+    if not API_TOKEN:
+        raise HTTPException(status_code=500, detail="API_TOKEN is not configured")
 
-文件示例：
+    if not authorization:
+        raise HTTPException(status_code=401, detail="Missing Authorization header")
 
-```text
-/data/backups/latest.sql
-/data/backups/backup_appdb_20260529_180000.sql
-```
-
-其中：
+    expected = f"Bearer {API_TOKEN}"
 
-```text
-latest.sql
-```
+    if authorization != expected:
+        raise HTTPException(status_code=403, detail="Invalid API token")
 
-始终指向最近一次备份内容。
 
----
-
-## 11. 自动恢复机制
+@app.get("/api/health")
+def health():
+    return {
+        "status": "ok",
+        "service": "postgresql-adminer-space"
+    }
 
-如果 Space 重启或重建后，`/home/user/pgdata` 不存在，但 `/data/backups/latest.sql` 存在，启动脚本会尝试自动恢复：
 
-```text
-/data/backups/latest.sql
-  ↓
-PostgreSQL appdb
-```
+@app.get("/api/db-health")
+def db_health(authorization: str | None = Header(default=None)):
+    verify_token(authorization)
 
-注意：
+    conn = psycopg2.connect(DATABASE_URL)
+    cur = conn.cursor()
+    cur.execute("SELECT 1;")
+    result = cur.fetchone()
+    cur.close()
+    conn.close()
 
-```text
-1. 自动恢复依赖 latest.sql 是否存在
-2. 如果 latest.sql 损坏，恢复会失败
-3. 建议定期检查 /data/backups 下的备份文件
-4. 重要数据库建议额外同步到 R2 / S3 / Hugging Face Dataset
+    return {
+        "status": "ok",
+        "db": result[0]
+    }
 ```
 
 ---
 
-## 12. 本地测试
+## 23. FastAPI 示例：文件索引表
 
-构建镜像：
+本项目建议大文件保存在 `/data/files`，数据库只保存文件索引。
 
-```bash
-docker build -t hf-postgres-adminer .
+管理员可以先创建文件索引表：
+
+```sql
+CREATE TABLE IF NOT EXISTS files (
+  id SERIAL PRIMARY KEY,
+  user_id TEXT,
+  filename TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  file_size BIGINT,
+  mime_type TEXT,
+  created_at TIMESTAMP DEFAULT now()
+);
 ```
 
-运行容器：
+API 示例：
+
+```python
+class FileRecord(BaseModel):
+    user_id: str | None = None
+    filename: str
+    file_path: str
+    file_size: int | None = None
+    mime_type: str | None = None
+
+
+@app.post("/api/files")
+def create_file(record: FileRecord, authorization: str | None = Header(default=None)):
+    verify_token(authorization)
+
+    conn = psycopg2.connect(DATABASE_URL)
+    cur = conn.cursor()
+
+    cur.execute(
+        """
+        INSERT INTO files (user_id, filename, file_path, file_size, mime_type)
+        VALUES (%s, %s, %s, %s, %s)
+        RETURNING id, created_at;
+        """,
+        (
+            record.user_id,
+            record.filename,
+            record.file_path,
+            record.file_size,
+            record.mime_type,
+        ),
+    )
+
+    row = cur.fetchone()
+    conn.commit()
+
+    cur.close()
+    conn.close()
+
+    return {
+        "id": row[0],
+        "created_at": row[1],
+        "filename": record.filename,
+        "file_path": record.file_path
+    }
 
-```bash
-docker run --rm -it \
-  -p 7860:7860 \
-  -p 5432:5432 \
-  -e POSTGRES_PASSWORD=your_strong_password \
-  -v $(pwd)/data:/data \
-  hf-postgres-adminer
-```
 
-访问 Adminer：
+@app.get("/api/files")
+def list_files(authorization: str | None = Header(default=None)):
+    verify_token(authorization)
 
-```text
-http://localhost:7860
-```
+    conn = psycopg2.connect(DATABASE_URL)
+    cur = conn.cursor()
 
-本地连接 PostgreSQL：
+    cur.execute(
+        """
+        SELECT id, user_id, filename, file_path, file_size, mime_type, created_at
+        FROM files
+        ORDER BY id DESC
+        LIMIT 100;
+        """
+    )
 
-```bash
-psql "postgresql://admin:your_strong_password@127.0.0.1:5432/appdb"
+    rows = cur.fetchall()
+
+    cur.close()
+    conn.close()
+
+    return [
+        {
+            "id": row[0],
+            "user_id": row[1],
+            "filename": row[2],
+            "file_path": row[3],
+            "file_size": row[4],
+            "mime_type": row[5],
+            "created_at": row[6],
+        }
+        for row in rows
+    ]
 ```
 
 ---
 
-## 13. 常用 PostgreSQL 命令
-
-进入数据库：
+## 24. FastAPI 示例：受控插入数据
 
-```bash
-psql -h 127.0.0.1 -U admin -d appdb
-```
+可以为不同业务创建专门接口，而不是开放通用 SQL。
 
-查看数据库：
+例如创建一个 RSS 文章表：
 
 ```sql
-\l
+CREATE TABLE IF NOT EXISTS rss_articles (
+  id SERIAL PRIMARY KEY,
+  source TEXT,
+  title TEXT NOT NULL,
+  url TEXT UNIQUE,
+  summary TEXT,
+  published_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT now()
+);
 ```
 
-查看当前数据库中的表：
-
-```sql
-\dt
+API 示例：
+
+```python
+class ArticleRecord(BaseModel):
+    source: str | None = None
+    title: str
+    url: str
+    summary: str | None = None
+    published_at: str | None = None
+
+
+@app.post("/api/rss/articles")
+def create_article(
+    article: ArticleRecord,
+    authorization: str | None = Header(default=None)
+):
+    verify_token(authorization)
+
+    conn = psycopg2.connect(DATABASE_URL)
+    cur = conn.cursor()
+
+    cur.execute(
+        """
+        INSERT INTO rss_articles (source, title, url, summary, published_at)
+        VALUES (%s, %s, %s, %s, %s)
+        ON CONFLICT (url) DO UPDATE SET
+          title = EXCLUDED.title,
+          summary = EXCLUDED.summary,
+          published_at = EXCLUDED.published_at
+        RETURNING id;
+        """,
+        (
+            article.source,
+            article.title,
+            article.url,
+            article.summary,
+            article.published_at,
+        ),
+    )
+
+    row = cur.fetchone()
+    conn.commit()
+
+    cur.close()
+    conn.close()
+
+    return {
+        "id": row[0],
+        "status": "saved"
+    }
 ```
 
-创建数据库：
+---
 
-```sql
-CREATE DATABASE project_db;
-```
+## 25. 不推荐开放通用 SQL API
 
-创建用户：
+不推荐提供如下接口：
 
-```sql
-CREATE USER project_user WITH PASSWORD 'replace_with_strong_password';
+```text
+POST /api/sql
 ```
 
-授权：
+并允许外部用户直接提交任意 SQL：
 
-```sql
-GRANT ALL PRIVILEGES ON DATABASE project_db TO project_user;
+```json
+{
+  "sql": "DROP TABLE users;"
+}
 ```
 
----
-
-## 14. 多项目隔离建议
+这非常危险，可能导致：
 
-如果这个 PostgreSQL Space 要服务多个项目，不建议所有项目共用 `admin` 用户。
+```text
+1. 数据库被删除
+2. 数据泄露
+3. 权限绕过
+4. SQL 注入
+5. 系统被恶意占用
+```
 
-推荐：
+如果确实需要管理级 SQL API，只建议管理员内部使用，并且必须同时满足：
 
 ```text
-一个项目一个 database
-一个项目一个 user
-一个项目一个 password
+1. 强 API Token
+2. IP 白名单
+3. Cloudflare Access
+4. 请求日志
+5. 限制 SQL 类型
+6. 禁止 DROP / TRUNCATE / ALTER 等危险语句
 ```
 
-示例：
+---
 
-```sql
-CREATE DATABASE rss_project;
-CREATE USER rss_user WITH PASSWORD 'rss_project_password';
-GRANT ALL PRIVILEGES ON DATABASE rss_project TO rss_user;
+## 26. API 服务依赖安装
 
-CREATE DATABASE image_project;
-CREATE USER image_user WITH PASSWORD 'image_project_password';
-GRANT ALL PRIVILEGES ON DATABASE image_project TO image_user;
-```
+如果增加 FastAPI API 服务，Dockerfile 需要额外安装 Python 依赖。
 
-业务项目连接时使用自己的数据库用户：
+可以在 Dockerfile 中增加：
 
-```env
-DATABASE_URL=postgresql://rss_user:rss_project_password@host:5432/rss_project
-```
+```dockerfile
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-pip \
+    && rm -rf /var/lib/apt/lists/*
 
----
+RUN pip3 install --break-system-packages \
+    fastapi \
+    uvicorn \
+    psycopg2-binary \
+    pydantic
+```
 
-## 15. 安全建议
+或者使用 `requirements.txt`：
 
-如果 Space 是 Public，请特别注意安全。
+```txt
+fastapi
+uvicorn
+psycopg2-binary
+pydantic
+```
 
-建议：
+然后在 Dockerfile 中加入：
 
-```text
-1. 不要把 POSTGRES_PASSWORD 写进代码仓库
-2. 使用 Hugging Face Secrets 保存数据库密码
-3. Adminer 必须使用强密码
-4. 不建议直接暴露 PostgreSQL 5432 给公网
-5. 尽量在外层增加 Cloudflare Access / OAuth / API Gateway
-6. 不要让业务项目使用 admin 超级用户
-7. 每个项目创建独立 database 和 user
-8. 定期备份数据库
-9. 重要备份同步到外部对象存储
-10. 不要在公开日志中输出数据库密码
+```dockerfile
+COPY requirements.txt /requirements.txt
+RUN pip3 install --break-system-packages -r /requirements.txt
 ```
 
 ---
 
-## 16. 适用场景
+## 27. 同时运行 Adminer 和 API 服务
+
+如果当前 Space 同时需要 Adminer 和 API 服务，可以让 FastAPI 作为主 Web 服务，并把 Adminer 放到 `/adminer.php`。
 
-适合：
+更简单的方式是继续让 Adminer 使用 `7860`，API 另外用内部端口。但 Hugging Face Space 通常只对外暴露一个 Web 端口，所以更推荐后续改成：
 
 ```text
-个人项目数据库
-AI Demo 数据库
-RSS / 爬虫 / 内容索引数据库
-测试环境数据库
-公开项目的轻量级共享数据库
-Hugging Face Space 内部应用数据库
-AI 生成文件索引系统
-用户文件索引系统
+7860:
+  /              API 首页
+  /docs          FastAPI 文档
+  /api/...       API 接口
+  /adminer       Adminer 管理入口
 ```
 
-不适合：
+如果暂时只需要 Adminer，可以不增加 API 服务。
+
+如果需要 API 服务，建议后续把启动方式升级为：
 
 ```text
-高并发生产数据库
-金融交易核心数据库
-强一致性要求极高的数据库
-需要专业数据库 SLA 的业务
-需要大量公网 PostgreSQL 长连接的业务
+Nginx / Caddy / FastAPI 静态代理
+  ├── /api
+  └── /adminer
 ```
 
 ---
 
-## 17. 默认连接信息
+## 28. 外部项目如何调用 API
 
-Adminer Web：
+示例：调用健康检查接口。
 
-```text
-https://你的-space.hf.space
+```bash
+curl -X GET "https://your-space-name.hf.space/api/db-health" \
+  -H "Authorization: Bearer replace_with_random_api_token"
 ```
 
-PostgreSQL：
+示例：创建文件索引。
 
-```text
-Host: 127.0.0.1
-Port: 5432
-User: admin
-Database: appdb
-Data Directory: /home/user/pgdata
-Backup Directory: /data/backups
-User File Directory: /data/files
+```bash
+curl -X POST "https://your-space-name.hf.space/api/files" \
+  -H "Authorization: Bearer replace_with_random_api_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "user_001",
+    "filename": "image_001.png",
+    "file_path": "/data/files/image_001.png",
+    "file_size": 245891,
+    "mime_type": "image/png"
+  }'
 ```
 
-注意：`127.0.0.1:5432` 是容器内部地址，主要给 Adminer 或同容器内应用使用。外部项目不建议直接连接该端口，推荐通过 API Gateway 或受控后端访问数据库。
+示例：写入 RSS 文章。
+
+```bash
+curl -X POST "https://your-space-name.hf.space/api/rss/articles" \
+  -H "Authorization: Bearer replace_with_random_api_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "example-rss",
+    "title": "Example Article",
+    "url": "https://example.com/article-1",
+    "summary": "This is an example article.",
+    "published_at": "2026-05-30T00:00:00"
+  }'
+```
 
 ---
 
-## 18. 重要说明
+## 29. 推荐的生产访问方式
 
-本项目基于官方 PostgreSQL Docker 镜像：
+公开 Space 推荐增加一层访问保护：
 
 ```text
-postgres:17
+Cloudflare Access
+  ↓
+Hugging Face Space
+  ↓
+FastAPI API Token
+  ↓
+PostgreSQL 项目用户
 ```
 
-部署时不需要拉取 `docker-library/postgres` 源码，只需要在 Dockerfile 中使用：
+最终安全层级：
 
-```dockerfile
-FROM postgres:17
+```text
+第一层：Cloudflare Access / OAuth / 登录白名单
+第二层：API Token
+第三层：PostgreSQL 项目账号
+第四层：database / schema 权限隔离
+第五层：定期备份
 ```
 
-即可。
+---
+
+## 30. 管理员操作流程总结
 
-本项目的关键设计是：
+管理员首次部署后，建议按以下步骤操作：
 
 ```text
-PostgreSQL 运行数据目录：/home/user/pgdata
-挂载大磁盘：/data
-数据库备份：/data/backups
-用户文件：/data/files
-导出文件：/data/exports
-生成文件：/data/generated
-```
-
-这样可以避免 PostgreSQL 直接在挂载 Bucket 上运行时出现文件权限或文件系统兼容问题，同时又能利用大容量挂载磁盘保存备份和业务文件。
+1. 设置 POSTGRES_PASSWORD
+2. 挂载 /data 存储
+3. 启动 Space
+4. 登录 Adminer
+5. 创建项目 database
+6. 创建项目 user
+7. 授权 database 和 schema 权限
+8. 创建业务表
+9. 配置 API_TOKEN
+10. 如果需要，对外开放 FastAPI 接口
+11. 外部项目通过 API Token 调用接口
+12. 定期检查 /data/backups 备份文件
+```
+
+推荐不要让外部项目直接获得 `admin` 账号，也不要让外部用户直接连接 PostgreSQL 5432 端口。