Update README.md

README.md

@@ -7,4 +7,453 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+
+title: PostgreSQL Adminer
+emoji: 🐘
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+-------------
+
+# PostgreSQL Adminer on Hugging Face Space
+
+这是一个用于在 Hugging Face Docker Space 上部署 PostgreSQL 数据库的项目。
+
+项目包含：
+
+* PostgreSQL 数据库服务
+* Adminer Web 数据库管理界面
+* 持久化数据目录 `/data/postgres`
+* Hugging Face Space Web 入口端口 `7860`
+
+默认设计：
+
+```text
+浏览器访问 Hugging Face Space
+        ↓
+Adminer Web 管理界面，端口 7860
+        ↓
+连接容器内部 PostgreSQL，端口 5432
+```
+
+PostgreSQL 数据库不建议直接暴露给公网，推荐通过 Adminer、API 服务或其他受控后端访问。
+
+---
+
+## 1. 文件结构
+
+仓库根目录应包含以下文件：
+
+```text
+README.md
+Dockerfile
+start.sh
+```
+
+---
+
+## 2. README Space 配置说明
+
+本项目使用 Hugging Face Docker Space。
+
+README 顶部的 YAML 配置如下：
+
+```yaml
+---
+title: PostgreSQL Adminer
+emoji: 🐘
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+```
+
+字段说明：
+
+| 字段               | 说明                        |
+| ---------------- | ------------------------- |
+| `title`          | Space 显示名称                |
+| `emoji`          | Space 图标                  |
+| `sdk: docker`    | 使用 Dockerfile 构建 Space    |
+| `app_port: 7860` | Hugging Face 对外暴露的 Web 端口 |
+| `pinned`         | 是否固定展示                    |
+
+---
+
+## 3. Dockerfile 示例
+
+```dockerfile
+FROM postgres:17
+
+ENV POSTGRES_USER=admin
+ENV POSTGRES_DB=appdb
+ENV PGDATA=/data/postgres
+ENV ADMINER_VERSION=4.8.1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    php \
+    php-pgsql \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -L -o /adminer.php https://github.com/vrana/adminer/releases/download/v${ADMINER_VERSION}/adminer-${ADMINER_VERSION}.php
+
+COPY start.sh /start.sh
+RUN chmod +x /start.sh
+
+EXPOSE 5432
+EXPOSE 7860
+
+CMD ["/start.sh"]
+```
+
+---
+
+## 4. start.sh 示例
+
+```bash
+#!/usr/bin/env bash
+set -e
+
+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
+
+mkdir -p "$PGDATA"
+chown -R postgres:postgres /data
+
+echo "Starting PostgreSQL..."
+docker-entrypoint.sh postgres &
+
+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."
+echo "Starting Adminer on port 7860..."
+
+php -S 0.0.0.0:7860 /adminer.php
+```
+
+---
+
+## 5. 环境变量
+
+请在 Hugging Face Space 的：
+
+```text
+Settings → Variables and secrets
+```
+
+中配置环境变量。
+
+### 必填变量
+
+| 变量名                 | 类型     | 示例                     | 说明               |
+| ------------------- | ------ | ---------------------- | ---------------- |
+| `POSTGRES_PASSWORD` | Secret | `your_strong_password` | PostgreSQL 管理员密码 |
+
+### 可选变量
+
+| 变量名               | 默认值              | 说明                |
+| ----------------- | ---------------- | ----------------- |
+| `POSTGRES_USER`   | `admin`          | PostgreSQL 管理员用户名 |
+| `POSTGRES_DB`     | `appdb`          | 默认数据库名称           |
+| `PGDATA`          | `/data/postgres` | PostgreSQL 数据目录   |
+| `ADMINER_VERSION` | `4.8.1`          | Adminer 版本        |
+
+推荐只把 `POSTGRES_PASSWORD` 放到 Secrets，不要写进 Dockerfile 或 README。
+
+---
+
+## 6. Hugging Face 持久化磁盘
+
+本项目默认把 PostgreSQL 数据写入：
+
+```text
+/data/postgres
+```
+
+如果你的 Space 挂载了持久化磁盘，并且挂载路径为 `/data`，数据库数据将保存在：
+
+```text
+/data/postgres
+```
+
+请确保 Hugging Face Space 已开启 Persistent Storage，否则 Space 重启、重建或休眠恢复后，数据库数据可能丢失。
+
+---
+
+## 7. Adminer 登录方式
+
+部署完成后，打开 Hugging Face Space 页面，会进入 Adminer 管理界面。
+
+登录时填写：
+
+```text
+System: PostgreSQL
+Server: 127.0.0.1
+Username: admin
+Password: 你的 POSTGRES_PASSWORD
+Database: appdb
+```
+
+如果你修改了 `POSTGRES_USER` 或 `POSTGRES_DB`，请使用你自己的配置。
+
+---
+
+## 8. 本地测试命令
+
+如果需要在本地测试，可以执行：
+
+```bash
+docker build -t hf-postgres-adminer .
+```
+
+运行容器：
+
+```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：
+
+```text
+http://localhost:7860
+```
+
+本地连接 PostgreSQL：
+
+```bash
+psql "postgresql://admin:your_strong_password@127.0.0.1:5432/appdb"
+```
+
+---
+
+## 9. 常用 PostgreSQL 命令
+
+进入容器后连接数据库：
+
+```bash
+psql -U admin -d appdb
+```
+
+查看数据库列表：
+
+```sql
+\l
+```
+
+查看表：
+
+```sql
+\dt
+```
+
+创建新数据库：
+
+```sql
+CREATE DATABASE project_db;
+```
+
+创建新用户：
+
+```sql
+CREATE USER project_user WITH PASSWORD 'replace_with_strong_password';
+```
+
+授权数据库：
+
+```sql
+GRANT ALL PRIVILEGES ON DATABASE project_db TO project_user;
+```
+
+---
+
+## 10. 推荐的多项目隔离方式
+
+如果该 PostgreSQL Space 要服务多个项目，建议不要所有项目共用 `admin` 用户。
+
+推荐方式：
+
+```text
+一个项目一个 database
+一个项目一个 role/user
+一个项目一个独立密码
+```
+
+示例：
+
+```sql
+CREATE DATABASE rss_project;
+CREATE USER rss_user WITH PASSWORD 'rss_project_password';
+GRANT ALL PRIVILEGES ON DATABASE rss_project TO rss_user;
+
+CREATE DATABASE image_project;
+CREATE USER image_user WITH PASSWORD 'image_project_password';
+GRANT ALL PRIVILEGES ON DATABASE image_project TO image_user;
+```
+
+业务项目连接时使用自己的数据库用户：
+
+```env
+DATABASE_URL=postgresql://rss_user:rss_project_password@host:5432/rss_project
+```
+
+---
+
+## 11. 安全建议
+
+如果 Space 设置为 Public，请特别注意安全。
+
+建议：
+
+```text
+1. 不要把 POSTGRES_PASSWORD 写进代码仓库
+2. 使用 Hugging Face Secrets 保存数据库密码
+3. 不建议直接暴露 PostgreSQL 5432 给公网
+4. Adminer 后台必须使用强密码
+5. 尽量在外层增加 Cloudflare Access / OAuth / API Gateway
+6. 不要让业务项目使用 PostgreSQL 超级用户 admin
+7. 为每个项目创建独立 database 和 user
+8. 定期备份数据库
+9. 不要使用 trust 认证
+10. 不要在公开日志中输出数据库密码
+```
+
+---
+
+## 12. 备份建议
+
+可以使用 `pg_dump` 备份数据库：
+
+```bash
+pg_dump -U admin -d appdb > backup.sql
+```
+
+恢复数据库：
+
+```bash
+psql -U admin -d appdb < backup.sql
+```
+
+建议定期将备份文件同步到：
+
+```text
+Hugging Face Dataset
+Cloudflare R2
+S3
+Backblaze B2
+其他对象存储
+```
+
+---
+
+## 13. 适用场景
+
+适合：
+
+```text
+个人项目数据库
+AI Demo 数据库
+RSS / 爬虫 / 内容索引数据库
+测试环境数据库
+公开项目的轻量级共享数据库
+Hugging Face Space 内部应用数据库
+```
+
+不适合：
+
+```text
+高并发生产数据库
+金融交易核心数据库
+强一致性要求极高的数据库
+需要公网 5432 长连接的大型数据库服务
+需要专业数据库运维和 SLA 的业务
+```
+
+---
+
+## 14. 注意事项
+
+本项目基于官方 PostgreSQL Docker 镜像：
+
+```text
+postgres:17
+```
+
+`docker-library/postgres` 是官方 PostgreSQL Docker 镜像的构建仓库。
+
+实际部署时不需要拉取 `docker-library/postgres` 源码，只需要在 Dockerfile 中使用：
+
+```dockerfile
+FROM postgres:17
+```
+
+即可。
+
+---
+
+## 15. 快速部署步骤
+
+1. 创建新的 Hugging Face Space
+2. Space SDK 选择 Docker
+3. 上传以下文件：
+
+```text
+README.md
+Dockerfile
+start.sh
+```
+
+4. 在 Space Settings 中添加 Secret：
+
+```text
+POSTGRES_PASSWORD=你的强密码
+```
+
+5. 如果需要持久化数据，开启 Persistent Storage
+6. 等待 Space 自动构建
+7. 打开 Space 页面
+8. 使用 Adminer 登录 PostgreSQL
+
+---
+
+## 16. 默认连接信息
+
+```text
+Adminer Web:
+https://你的-space.hf.space
+
+PostgreSQL Host:
+127.0.0.1
+
+PostgreSQL Port:
+5432
+
+PostgreSQL User:
+admin
+
+PostgreSQL Database:
+appdb
+
+PostgreSQL Data Directory:
+/data/postgres
+```
+
+注意：`127.0.0.1:5432` 是容器内部地址，主要给 Adminer 或同容器内应用使用。外部项目不建议直接连接该端口，推荐通过 API Gateway 或受控后端访问数据库。
+