darkfire514 commited on
Commit
6a977ba
·
verified ·
1 Parent(s): 7bccdc7

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +428 -172
README.md CHANGED
@@ -7,45 +7,26 @@ sdk: docker
7
  pinned: false
8
  ---
9
 
10
- ---
11
-
12
- title: PostgreSQL Adminer
13
- emoji: 🐘
14
- colorFrom: blue
15
- colorTo: indigo
16
- sdk: docker
17
- app_port: 7860
18
- pinned: false
19
- -------------
20
-
21
  # PostgreSQL Adminer on Hugging Face Space
22
 
23
- 这是一个用于在 Hugging Face Docker Space 上部署 PostgreSQL 数据库的项目。
24
-
25
- 项目包含:
26
-
27
- * PostgreSQL 数据库服务
28
- * Adminer Web 数据库管理界面
29
- * 持久化数据目录 `/data/postgres`
30
- * Hugging Face Space Web 入口端口 `7860`
31
 
32
- 默认设计:
33
 
34
  ```text
35
- 浏览器访问 Hugging Face Space
36
- ↓
37
- Adminer Web 管理界面,端口 7860
38
- ↓
39
- 连接容器内部 PostgreSQL,端口 5432
40
  ```
41
 
42
- PostgreSQL 数据库不建议直接暴露给公网,推荐通过 Adminer、API 服务或其他受控后端访问。
43
 
44
  ---
45
 
46
- ## 1. 文件结构
47
 
48
- 仓库根目录应包含以下文件:
49
 
50
  ```text
51
  README.md
@@ -55,44 +36,62 @@ start.sh
55
 
56
  ---
57
 
58
- ## 2. README Space 配置说明
59
 
60
- 本项目使用 Hugging Face Docker Space。
 
 
 
 
 
 
 
 
61
 
62
- README 顶部的 YAML 配置如下:
63
 
64
- ```yaml
65
- ---
66
- title: PostgreSQL Adminer
67
- emoji: 🐘
68
- colorFrom: blue
69
- colorTo: indigo
70
- sdk: docker
71
- app_port: 7860
72
- pinned: false
73
- ---
74
- ```
75
 
76
- 字段说明:
 
 
 
 
 
 
 
 
 
 
77
 
78
- | 字段 | 说明 |
79
- | ---------------- | ------------------------- |
80
- | `title` | Space 显示名称 |
81
- | `emoji` | Space 图标 |
82
- | `sdk: docker` | 使用 Dockerfile 构建 Space |
83
- | `app_port: 7860` | Hugging Face 对外暴露的 Web 端口 |
84
- | `pinned` | 是否固定展示 |
85
 
86
  ---
87
 
88
- ## 3. Dockerfile 示例
89
 
90
  ```dockerfile
91
  FROM postgres:17
92
 
93
  ENV POSTGRES_USER=admin
94
  ENV POSTGRES_DB=appdb
95
- ENV PGDATA=/data/postgres
 
 
 
 
 
 
 
 
 
 
 
 
 
 
96
  ENV ADMINER_VERSION=4.8.1
97
 
98
  RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -100,9 +99,11 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
100
  php \
101
  php-pgsql \
102
  ca-certificates \
 
103
  && rm -rf /var/lib/apt/lists/*
104
 
105
- RUN curl -L -o /adminer.php https://github.com/vrana/adminer/releases/download/v${ADMINER_VERSION}/adminer-${ADMINER_VERSION}.php
 
106
 
107
  COPY start.sh /start.sh
108
  RUN chmod +x /start.sh
@@ -115,40 +116,203 @@ CMD ["/start.sh"]
115
 
116
  ---
117
 
118
- ## 4. start.sh 示例
119
 
120
  ```bash
121
  #!/usr/bin/env bash
122
  set -e
123
 
 
 
 
 
124
  if [ -z "$POSTGRES_PASSWORD" ]; then
125
  echo "ERROR: POSTGRES_PASSWORD is not set."
126
  echo "Please set POSTGRES_PASSWORD in Hugging Face Space Secrets."
127
  exit 1
128
  fi
129
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
130
  mkdir -p "$PGDATA"
131
- chown -R postgres:postgres /data
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
132
 
133
  echo "Starting PostgreSQL..."
134
  docker-entrypoint.sh postgres &
135
 
 
 
136
  echo "Waiting for PostgreSQL to become ready..."
 
137
  until pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; do
138
  sleep 2
139
  done
140
 
141
  echo "PostgreSQL is ready."
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
142
  echo "Starting Adminer on port 7860..."
 
 
 
 
 
143
 
144
  php -S 0.0.0.0:7860 /adminer.php
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
145
  ```
146
 
 
 
 
 
 
 
 
 
 
147
  ---
148
 
149
- ## 5. 环境变量
150
 
151
- 请在 Hugging Face Space 的:
152
 
153
  ```text
154
  Settings → Variables and secrets
@@ -156,48 +320,78 @@ Settings → Variables and secrets
156
 
157
  中配置环境变量。
158
 
159
- ### 必填变量
160
 
161
  | 变量名 | 类型 | 示例 | 说明 |
162
  | ------------------- | ------ | ---------------------- | ---------------- |
163
  | `POSTGRES_PASSWORD` | Secret | `your_strong_password` | PostgreSQL 管理员密码 |
164
 
165
- ### 可选变量
166
 
167
- | 变量名 | 默认值 | 说明 |
168
- | ----------------- | ---------------- | ----------------- |
169
- | `POSTGRES_USER` | `admin` | PostgreSQL 管理员用户名 |
170
- | `POSTGRES_DB` | `appdb` | 默认数据库名称 |
171
- | `PGDATA` | `/data/postgres` | PostgreSQL 数据目录 |
172
- | `ADMINER_VERSION` | `4.8.1` | Adminer 版本 |
 
 
 
 
 
173
 
174
- 推荐只把 `POSTGRES_PASSWORD` 放到 Secrets,不要写进 Dockerfile 或 README。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
175
 
176
  ---
177
 
178
- ## 6. Hugging Face 持久化磁盘
179
 
180
- 本项目默认把 PostgreSQL 数据写入:
181
 
182
  ```text
183
- /data/postgres
184
  ```
185
 
186
- 如果你的 Space 挂载了持久化磁盘,并且挂载路径为 `/data`,数据库数据将保存在:
187
 
188
  ```text
189
- /data/postgres
 
 
190
  ```
191
 
192
- 请确保 Hugging Face Space 已开启 Persistent Storage,否则 Space 重启、重建或休眠恢复后,数据库数据可能丢失。
 
 
 
 
 
 
 
 
 
193
 
194
  ---
195
 
196
- ## 7. Adminer 登录方式
197
 
198
- 部署完成后,打开 Hugging Face Space 页面,会进入 Adminer 管理界面。
199
 
200
- 登录时填写:
201
 
202
  ```text
203
  System: PostgreSQL
@@ -207,13 +401,116 @@ Password: 你的 POSTGRES_PASSWORD
207
  Database: appdb
208
  ```
209
 
210
- 如果你修改了 `POSTGRES_USER` 或 `POSTGRES_DB`,请使用你自己的配置。
 
 
 
 
 
211
 
212
  ---
213
 
214
- ## 8. 本地测试命令
 
 
 
 
 
 
 
 
 
 
 
215
 
216
- 如果需要在本地测试,可以执行:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
217
 
218
  ```bash
219
  docker build -t hf-postgres-adminer .
@@ -244,39 +541,39 @@ psql "postgresql://admin:your_strong_password@127.0.0.1:5432/appdb"
244
 
245
  ---
246
 
247
- ## 9. 常用 PostgreSQL 命令
248
 
249
- 进入容器后连接数据库:
250
 
251
  ```bash
252
- psql -U admin -d appdb
253
  ```
254
 
255
- 查看数据库列表:
256
 
257
  ```sql
258
  \l
259
  ```
260
 
261
- 查看表:
262
 
263
  ```sql
264
  \dt
265
  ```
266
 
267
- 创建新数据库:
268
 
269
  ```sql
270
  CREATE DATABASE project_db;
271
  ```
272
 
273
- 创建新用户:
274
 
275
  ```sql
276
  CREATE USER project_user WITH PASSWORD 'replace_with_strong_password';
277
  ```
278
 
279
- 授权数据库:
280
 
281
  ```sql
282
  GRANT ALL PRIVILEGES ON DATABASE project_db TO project_user;
@@ -284,16 +581,16 @@ GRANT ALL PRIVILEGES ON DATABASE project_db TO project_user;
284
 
285
  ---
286
 
287
- ## 10. 推荐的多项目隔离方式
288
 
289
- 如果该 PostgreSQL Space 要服务多个项目,建议不要所有项目共用 `admin` 用户。
290
 
291
- 推荐方式:
292
 
293
  ```text
294
  一个项目一个 database
295
- 一个项目一个 role/user
296
- 一个项目一个独立密码
297
  ```
298
 
299
  示例:
@@ -316,54 +613,28 @@ DATABASE_URL=postgresql://rss_user:rss_project_password@host:5432/rss_project
316
 
317
  ---
318
 
319
- ## 11. 安全建议
320
 
321
- 如果 Space 设置为 Public,请特别注意安全。
322
 
323
  建议:
324
 
325
  ```text
326
  1. 不要把 POSTGRES_PASSWORD 写进代码仓库
327
  2. 使用 Hugging Face Secrets 保存数据库密码
328
- 3. 不建议直接暴露 PostgreSQL 5432 给公网
329
- 4. Adminer 后台必须使用强密码
330
  5. 尽量在外层增加 Cloudflare Access / OAuth / API Gateway
331
- 6. 不要让业务项目使用 PostgreSQL 超级用户 admin
332
- 7. 为每个项目创建独立 database 和 user
333
  8. 定期备份数据库
334
- 9. 不要使用 trust 认证
335
  10. 不要在公开日志中输出数据库密码
336
  ```
337
 
338
  ---
339
 
340
- ## 12. 备份建议
341
-
342
- 可以使用 `pg_dump` 备份数据库:
343
-
344
- ```bash
345
- pg_dump -U admin -d appdb > backup.sql
346
- ```
347
-
348
- 恢复数据库:
349
-
350
- ```bash
351
- psql -U admin -d appdb < backup.sql
352
- ```
353
-
354
- 建议定期将备份文件同步到:
355
-
356
- ```text
357
- Hugging Face Dataset
358
- Cloudflare R2
359
- S3
360
- Backblaze B2
361
- 其他对象存储
362
- ```
363
-
364
- ---
365
-
366
- ## 13. 适用场景
367
 
368
  适合:
369
 
@@ -374,6 +645,8 @@ RSS / 爬虫 / 内容索引数据库
374
  测试环境数据库
375
  公开项目的轻量级共享数据库
376
  Hugging Face Space 内部应用数据库
 
 
377
  ```
378
 
379
  不适合:
@@ -382,78 +655,61 @@ Hugging Face Space 内部应用数据库
382
  高并发生产数据库
383
  金融交易核心数据库
384
  强一致性要求极高的数据库
385
- 需要公网 5432 长连接的大型数据库服务
386
- 需要专业数据库运维和 SLA 的业务
387
  ```
388
 
389
  ---
390
 
391
- ## 14. 注意事项
392
 
393
- 本项目基于官方 PostgreSQL Docker 镜像:
394
 
395
  ```text
396
- postgres:17
397
  ```
398
 
399
- `docker-library/postgres` 是官方 PostgreSQL Docker 镜像的构建仓库。
400
-
401
- 实际部署时不需要拉取 `docker-library/postgres` 源码,只需要在 Dockerfile 中使用:
402
 
403
- ```dockerfile
404
- FROM postgres:17
 
 
 
 
 
 
405
  ```
406
 
407
- 即可。
408
 
409
  ---
410
 
411
- ## 15. 快速部署步骤
412
 
413
- 1. 创建新的 Hugging Face Space
414
- 2. Space SDK 选择 Docker
415
- 3. 上传以下文件:
416
 
417
  ```text
418
- README.md
419
- Dockerfile
420
- start.sh
421
  ```
422
 
423
- 4. 在 Space Settings 中添加 Secret:
424
 
425
- ```text
426
- POSTGRES_PASSWORD=你的强密码
427
  ```
428
 
429
- 5. 如果需要持久化数据,开启 Persistent Storage
430
- 6. 等待 Space 自动构建
431
- 7. 打开 Space 页面
432
- 8. 使用 Adminer 登录 PostgreSQL
433
-
434
- ---
435
 
436
- ## 16. 默认连接信息
437
 
438
  ```text
439
- Adminer Web:
440
- https://你的-space.hf.space
441
-
442
- PostgreSQL Host:
443
- 127.0.0.1
444
-
445
- PostgreSQL Port:
446
- 5432
447
-
448
- PostgreSQL User:
449
- admin
450
-
451
- PostgreSQL Database:
452
- appdb
453
-
454
- PostgreSQL Data Directory:
455
- /data/postgres
456
  ```
457
 
458
- 注意:`127.0.0.1:5432` 是容器内部地址,主要给 Adminer 或同容器内应用使用。外部项目不建议直接连接该端口,推荐通过 API Gateway 或受控后端访问数据库。
459
-
 
7
  pinned: false
8
  ---
9
 
 
 
 
 
 
 
 
 
 
 
 
10
  # PostgreSQL Adminer on Hugging Face Space
11
 
12
+ 这是一个用于在 Hugging Face Docker Space 上部署 PostgreSQL 数据库与 Adminer 管理界面的项目。
 
 
 
 
 
 
 
13
 
14
+ 本项目采用以下设计:
15
 
16
  ```text
17
+ PostgreSQL 程序:运行在 Hugging Face Space 容器内
18
+ PostgreSQL 数据目录:使用 Space 本地磁盘 /home/user/pgdata
19
+ 挂载大磁盘 /data:用于保存备份、用户文件、导出文件和生成文件
20
+ Adminer Web 管理界面:通过 7860 端口访问
 
21
  ```
22
 
23
+ 不建议把 PostgreSQL 的运行数据目录直接放到挂载磁盘 `/data/postgres`,因为 PostgreSQL 对底层文件系统权限、锁、随机读写、WAL、fsync 等要求较高。挂载磁盘更适合保存备份文件和业务文件。
24
 
25
  ---
26
 
27
+ ## 1. 项目结构
28
 
29
+ 仓库根目录包含以下文件:
30
 
31
  ```text
32
  README.md
 
36
 
37
  ---
38
 
39
+ ## 2. 整体架构
40
 
41
+ ```text
42
+ 浏览器
43
+ ↓
44
+ Hugging Face Space Web 入口,端口 7860
45
+ ↓
46
+ Adminer 管理界面
47
+ ↓
48
+ PostgreSQL,容器内部 5432 端口
49
+ ```
50
 
51
+ 目录设计:
52
 
53
+ ```text
54
+ /home/user/pgdata
55
+ └── PostgreSQL 正在运行的数据库文件
 
 
 
 
 
 
 
 
56
 
57
+ /data
58
+ ├── backups
59
+ │ ├── latest.sql
60
+ │ └── backup_appdb_YYYYMMDD_HHMMSS.sql
61
+ ├── files
62
+ │ └── 用户上传文件
63
+ ├── exports
64
+ │ └── 导出的 CSV / JSON / SQL 文件
65
+ └── generated
66
+ └── AI 生成文件、图片、视频等
67
+ ```
68
 
69
+ 数据库中建议只保存文件路径、文件名、文件大小、MIME 类型等索引信息,不建议把大文件直接写入 PostgreSQL。
 
 
 
 
 
 
70
 
71
  ---
72
 
73
+ ## 3. Dockerfile
74
 
75
  ```dockerfile
76
  FROM postgres:17
77
 
78
  ENV POSTGRES_USER=admin
79
  ENV POSTGRES_DB=appdb
80
+
81
+ # PostgreSQL 运行中的数据库目录:使用 Space 本地磁盘
82
+ ENV PGDATA=/home/user/pgdata
83
+
84
+ # 挂载大磁盘目录:用于备份、用户文件、导出文件
85
+ ENV DATA_DIR=/data
86
+ ENV BACKUP_DIR=/data/backups
87
+ ENV USER_FILE_DIR=/data/files
88
+ ENV EXPORT_DIR=/data/exports
89
+ ENV GENERATED_DIR=/data/generated
90
+
91
+ # 自动备份间隔,默认 1 小时
92
+ ENV BACKUP_INTERVAL_SECONDS=3600
93
+
94
+ # Adminer 版本
95
  ENV ADMINER_VERSION=4.8.1
96
 
97
  RUN apt-get update && apt-get install -y --no-install-recommends \
 
99
  php \
100
  php-pgsql \
101
  ca-certificates \
102
+ procps \
103
  && rm -rf /var/lib/apt/lists/*
104
 
105
+ RUN curl -L -o /adminer.php \
106
+ https://github.com/vrana/adminer/releases/download/v${ADMINER_VERSION}/adminer-${ADMINER_VERSION}.php
107
 
108
  COPY start.sh /start.sh
109
  RUN chmod +x /start.sh
 
116
 
117
  ---
118
 
119
+ ## 4. start.sh
120
 
121
  ```bash
122
  #!/usr/bin/env bash
123
  set -e
124
 
125
+ echo "======================================"
126
+ echo "PostgreSQL + Adminer for Hugging Face"
127
+ echo "======================================"
128
+
129
  if [ -z "$POSTGRES_PASSWORD" ]; then
130
  echo "ERROR: POSTGRES_PASSWORD is not set."
131
  echo "Please set POSTGRES_PASSWORD in Hugging Face Space Secrets."
132
  exit 1
133
  fi
134
 
135
+ export POSTGRES_USER="${POSTGRES_USER:-admin}"
136
+ export POSTGRES_DB="${POSTGRES_DB:-appdb}"
137
+ export PGDATA="${PGDATA:-/home/user/pgdata}"
138
+
139
+ export DATA_DIR="${DATA_DIR:-/data}"
140
+ export BACKUP_DIR="${BACKUP_DIR:-/data/backups}"
141
+ export USER_FILE_DIR="${USER_FILE_DIR:-/data/files}"
142
+ export EXPORT_DIR="${EXPORT_DIR:-/data/exports}"
143
+ export GENERATED_DIR="${GENERATED_DIR:-/data/generated}"
144
+ export BACKUP_INTERVAL_SECONDS="${BACKUP_INTERVAL_SECONDS:-3600}"
145
+
146
+ echo "POSTGRES_USER=$POSTGRES_USER"
147
+ echo "POSTGRES_DB=$POSTGRES_DB"
148
+ echo "PGDATA=$PGDATA"
149
+ echo "DATA_DIR=$DATA_DIR"
150
+ echo "BACKUP_DIR=$BACKUP_DIR"
151
+ echo "USER_FILE_DIR=$USER_FILE_DIR"
152
+ echo "EXPORT_DIR=$EXPORT_DIR"
153
+ echo "GENERATED_DIR=$GENERATED_DIR"
154
+ echo "BACKUP_INTERVAL_SECONDS=$BACKUP_INTERVAL_SECONDS"
155
+
156
+ echo "Creating directories..."
157
+
158
  mkdir -p "$PGDATA"
159
+ mkdir -p "$BACKUP_DIR"
160
+ mkdir -p "$USER_FILE_DIR"
161
+ mkdir -p "$EXPORT_DIR"
162
+ mkdir -p "$GENERATED_DIR"
163
+
164
+ # PostgreSQL 数据目录需要 postgres 用户权限
165
+ chown -R postgres:postgres "$PGDATA" || true
166
+ chmod 700 "$PGDATA" || true
167
+
168
+ # /data 是挂载大磁盘,可能不支持 chown,所以这里允许失败
169
+ chmod -R 755 "$DATA_DIR" || true
170
+
171
+ echo "Directory status:"
172
+ ls -ld "$PGDATA" || true
173
+ ls -ld "$DATA_DIR" || true
174
+ ls -ld "$BACKUP_DIR" || true
175
+ ls -ld "$USER_FILE_DIR" || true
176
+ ls -ld "$EXPORT_DIR" || true
177
+ ls -ld "$GENERATED_DIR" || true
178
+
179
+ RESTORE_BACKUP=0
180
+
181
+ if [ ! -s "$PGDATA/PG_VERSION" ]; then
182
+ echo "No existing PostgreSQL data directory found."
183
+
184
+ if [ -f "$BACKUP_DIR/latest.sql" ]; then
185
+ echo "Backup file found: $BACKUP_DIR/latest.sql"
186
+ echo "Database will be restored after PostgreSQL initialization."
187
+ RESTORE_BACKUP=1
188
+ else
189
+ echo "No backup file found. A new database will be initialized."
190
+ fi
191
+ else
192
+ echo "Existing PostgreSQL data directory found."
193
+ fi
194
 
195
  echo "Starting PostgreSQL..."
196
  docker-entrypoint.sh postgres &
197
 
198
+ POSTGRES_PID=$!
199
+
200
  echo "Waiting for PostgreSQL to become ready..."
201
+
202
  until pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; do
203
  sleep 2
204
  done
205
 
206
  echo "PostgreSQL is ready."
207
+
208
+ if [ "$RESTORE_BACKUP" = "1" ]; then
209
+ echo "Restoring database from $BACKUP_DIR/latest.sql ..."
210
+
211
+ psql \
212
+ -h 127.0.0.1 \
213
+ -U "$POSTGRES_USER" \
214
+ -d "$POSTGRES_DB" \
215
+ < "$BACKUP_DIR/latest.sql" || {
216
+ echo "WARNING: Restore failed. Please check backup file."
217
+ }
218
+
219
+ echo "Restore process finished."
220
+ fi
221
+
222
+ create_backup() {
223
+ TIMESTAMP="$(date +%Y%m%d_%H%M%S)"
224
+ BACKUP_FILE="$BACKUP_DIR/backup_${POSTGRES_DB}_${TIMESTAMP}.sql"
225
+ LATEST_FILE="$BACKUP_DIR/latest.sql"
226
+
227
+ echo "Creating backup: $BACKUP_FILE"
228
+
229
+ pg_dump \
230
+ -h 127.0.0.1 \
231
+ -U "$POSTGRES_USER" \
232
+ -d "$POSTGRES_DB" \
233
+ > "$BACKUP_FILE.tmp"
234
+
235
+ mv "$BACKUP_FILE.tmp" "$BACKUP_FILE"
236
+ cp "$BACKUP_FILE" "$LATEST_FILE"
237
+
238
+ echo "Backup saved:"
239
+ echo "- $BACKUP_FILE"
240
+ echo "- $LATEST_FILE"
241
+ }
242
+
243
+ backup_loop() {
244
+ echo "Backup loop started. Interval: ${BACKUP_INTERVAL_SECONDS}s"
245
+
246
+ while true; do
247
+ sleep "$BACKUP_INTERVAL_SECONDS"
248
+
249
+ if pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; then
250
+ create_backup || echo "WARNING: Backup failed."
251
+ else
252
+ echo "WARNING: PostgreSQL is not ready. Backup skipped."
253
+ fi
254
+ done
255
+ }
256
+
257
+ # 启动后先做一次备份,避免 latest.sql 长时间不存在
258
+ if pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; then
259
+ create_backup || echo "WARNING: Initial backup failed."
260
+ fi
261
+
262
+ backup_loop &
263
+
264
  echo "Starting Adminer on port 7860..."
265
+ echo "Adminer login:"
266
+ echo "System: PostgreSQL"
267
+ echo "Server: 127.0.0.1"
268
+ echo "Username: $POSTGRES_USER"
269
+ echo "Database: $POSTGRES_DB"
270
 
271
  php -S 0.0.0.0:7860 /adminer.php
272
+
273
+ wait "$POSTGRES_PID"
274
+ ```
275
+
276
+ ---
277
+
278
+ ## 5. Hugging Face Space 配置
279
+
280
+ 创建 Hugging Face Space 时选择:
281
+
282
+ ```text
283
+ SDK: Docker
284
+ Visibility: Public 或 Private
285
+ Hardware: CPU Basic 即可
286
+ ```
287
+
288
+ README 顶部需要包含:
289
+
290
+ ```yaml
291
+ ---
292
+ title: PostgreSQL Adminer
293
+ emoji: 🐘
294
+ colorFrom: blue
295
+ colorTo: indigo
296
+ sdk: docker
297
+ app_port: 7860
298
+ pinned: false
299
+ ---
300
  ```
301
 
302
+ 其中:
303
+
304
+ | 配置 | 说明 |
305
+ | ---------------- | -------------------------------- |
306
+ | `sdk: docker` | 使用 Dockerfile 构建 Space |
307
+ | `app_port: 7860` | Hugging Face 对外暴露 Adminer Web 页面 |
308
+ | `title` | Space 显示名称 |
309
+ | `emoji` | Space 图标 |
310
+
311
  ---
312
 
313
+ ## 6. 环境变量
314
 
315
+ 在 Hugging Face Space 的:
316
 
317
  ```text
318
  Settings → Variables and secrets
 
320
 
321
  中配置环境变量。
322
 
323
+ ### 必填 Secret
324
 
325
  | 变量名 | 类型 | 示例 | 说明 |
326
  | ------------------- | ------ | ---------------------- | ---------------- |
327
  | `POSTGRES_PASSWORD` | Secret | `your_strong_password` | PostgreSQL 管理员密码 |
328
 
329
+ ### 推荐 Variables
330
 
331
+ | 变量名 | 默认值 | 说明 |
332
+ | ------------------------- | ------------------- | ----------------- |
333
+ | `POSTGRES_USER` | `admin` | PostgreSQL 管理员用户名 |
334
+ | `POSTGRES_DB` | `appdb` | 默认数据库名称 |
335
+ | `PGDATA` | `/home/user/pgdata` | PostgreSQL 运行数据目录 |
336
+ | `DATA_DIR` | `/data` | 挂载大磁盘根目录 |
337
+ | `BACKUP_DIR` | `/data/backups` | 数据库备份目录 |
338
+ | `USER_FILE_DIR` | `/data/files` | 用户上传文件目录 |
339
+ | `EXPORT_DIR` | `/data/exports` | 导出文件目录 |
340
+ | `GENERATED_DIR` | `/data/generated` | AI 生成文件目录 |
341
+ | `BACKUP_INTERVAL_SECONDS` | `3600` | 自动备份间隔,单位为秒 |
342
 
343
+ 示例:
344
+
345
+ ```env
346
+ POSTGRES_USER=admin
347
+ POSTGRES_DB=appdb
348
+ PGDATA=/home/user/pgdata
349
+ DATA_DIR=/data
350
+ BACKUP_DIR=/data/backups
351
+ USER_FILE_DIR=/data/files
352
+ EXPORT_DIR=/data/exports
353
+ GENERATED_DIR=/data/generated
354
+ BACKUP_INTERVAL_SECONDS=3600
355
+ ```
356
+
357
+ 不要把 `POSTGRES_PASSWORD` 写进代码仓库或 README 的真实值中,应放入 Hugging Face Secret。
358
 
359
  ---
360
 
361
+ ## 7. 挂载磁盘设置
362
 
363
+ 建议将 Hugging Face Storage Bucket 挂载到:
364
 
365
  ```text
366
+ /data
367
  ```
368
 
369
+ 推荐配置:
370
 
371
  ```text
372
+ Mount path: /data
373
+ Access mode: Read & Write
374
+ Bucket visibility: Private
375
  ```
376
 
377
+ 挂载磁盘 `/data` 用于保存:
378
+
379
+ ```text
380
+ /data/backups 数据库备份
381
+ /data/files 用户上传文件
382
+ /data/exports 导出文件
383
+ /data/generated AI 生成文件
384
+ ```
385
+
386
+ 不建议将 PostgreSQL 的 `PGDATA` 设置为 `/data/postgres`。
387
 
388
  ---
389
 
390
+ ## 8. Adminer 登录方式
391
 
392
+ 部署完成后,打开 Hugging Face Space 页面,会看到 Adminer 登录界面。
393
 
394
+ 填写:
395
 
396
  ```text
397
  System: PostgreSQL
 
401
  Database: appdb
402
  ```
403
 
404
+ 如果你修改了环境变量,请使用自己的值:
405
+
406
+ ```text
407
+ Username: POSTGRES_USER
408
+ Database: POSTGRES_DB
409
+ ```
410
 
411
  ---
412
 
413
+ ## 9. 数据保存逻辑
414
+
415
+ 本项目采用“数据库索引 + 文件系统存储”的设计。
416
+
417
+ 不推荐把大文件直接写入 PostgreSQL,例如:
418
+
419
+ ```sql
420
+ CREATE TABLE files (
421
+ id SERIAL PRIMARY KEY,
422
+ content BYTEA
423
+ );
424
+ ```
425
 
426
+ 推荐把文件保存到 `/data/files`,数据库中只保存文件路径:
427
+
428
+ ```sql
429
+ CREATE TABLE files (
430
+ id SERIAL PRIMARY KEY,
431
+ user_id TEXT,
432
+ filename TEXT NOT NULL,
433
+ file_path TEXT NOT NULL,
434
+ file_size BIGINT,
435
+ mime_type TEXT,
436
+ created_at TIMESTAMP DEFAULT now()
437
+ );
438
+ ```
439
+
440
+ 示例记录:
441
+
442
+ ```text
443
+ filename: image_001.png
444
+ file_path: /data/files/image_001.png
445
+ file_size: 245891
446
+ mime_type: image/png
447
+ ```
448
+
449
+ ---
450
+
451
+ ## 10. 自动备份机制
452
+
453
+ 启动脚本会自动执行备份。
454
+
455
+ 默认备份间隔:
456
+
457
+ ```text
458
+ 3600 秒,即 1 小时
459
+ ```
460
+
461
+ 可以通过环境变量修改:
462
+
463
+ ```env
464
+ BACKUP_INTERVAL_SECONDS=1800
465
+ ```
466
+
467
+ 备份文件保存到:
468
+
469
+ ```text
470
+ /data/backups
471
+ ```
472
+
473
+ 文件示例:
474
+
475
+ ```text
476
+ /data/backups/latest.sql
477
+ /data/backups/backup_appdb_20260529_180000.sql
478
+ ```
479
+
480
+ 其中:
481
+
482
+ ```text
483
+ latest.sql
484
+ ```
485
+
486
+ 始终指向最近一次备份内容。
487
+
488
+ ---
489
+
490
+ ## 11. 自动恢复机制
491
+
492
+ 如果 Space 重启或重建后,`/home/user/pgdata` 不存在,但 `/data/backups/latest.sql` 存在,启动脚本会尝试自动恢复:
493
+
494
+ ```text
495
+ /data/backups/latest.sql
496
+ ↓
497
+ PostgreSQL appdb
498
+ ```
499
+
500
+ 注意:
501
+
502
+ ```text
503
+ 1. 自动恢复依赖 latest.sql 是否存在
504
+ 2. 如果 latest.sql 损坏,恢复会失败
505
+ 3. 建议定期检查 /data/backups 下的备份文件
506
+ 4. 重要数据库建议额外同步到 R2 / S3 / Hugging Face Dataset
507
+ ```
508
+
509
+ ---
510
+
511
+ ## 12. 本地测试
512
+
513
+ 构建镜像:
514
 
515
  ```bash
516
  docker build -t hf-postgres-adminer .
 
541
 
542
  ---
543
 
544
+ ## 13. 常用 PostgreSQL 命令
545
 
546
+ 进入数据库:
547
 
548
  ```bash
549
+ psql -h 127.0.0.1 -U admin -d appdb
550
  ```
551
 
552
+ 查看数据库:
553
 
554
  ```sql
555
  \l
556
  ```
557
 
558
+ 查看当前数据库中的表:
559
 
560
  ```sql
561
  \dt
562
  ```
563
 
564
+ 创建数据库:
565
 
566
  ```sql
567
  CREATE DATABASE project_db;
568
  ```
569
 
570
+ 创建用户:
571
 
572
  ```sql
573
  CREATE USER project_user WITH PASSWORD 'replace_with_strong_password';
574
  ```
575
 
576
+ 授权:
577
 
578
  ```sql
579
  GRANT ALL PRIVILEGES ON DATABASE project_db TO project_user;
 
581
 
582
  ---
583
 
584
+ ## 14. 多项目隔离建议
585
 
586
+ 如果这个 PostgreSQL Space 要服务多个项目,不建议所有项目共用 `admin` 用户。
587
 
588
+ 推荐:
589
 
590
  ```text
591
  一个项目一个 database
592
+ 一个项目一个 user
593
+ 一个项目一个 password
594
  ```
595
 
596
  示例:
 
613
 
614
  ---
615
 
616
+ ## 15. 安全建议
617
 
618
+ 如果 Space 是 Public,请特别注意安全。
619
 
620
  建议:
621
 
622
  ```text
623
  1. 不要把 POSTGRES_PASSWORD 写进代码仓库
624
  2. 使用 Hugging Face Secrets 保存数据库密码
625
+ 3. Adminer 必须使用强密码
626
+ 4. 不建议直接暴露 PostgreSQL 5432 给公网
627
  5. 尽量在外层增加 Cloudflare Access / OAuth / API Gateway
628
+ 6. 不要让业务项目使用 admin 超级用户
629
+ 7. 每个项目创建独立 database 和 user
630
  8. 定期备份数据库
631
+ 9. 重要备份同步到外部对象存储
632
  10. 不要在公开日志中输出数据库密码
633
  ```
634
 
635
  ---
636
 
637
+ ## 16. 适用场景
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
638
 
639
  适合:
640
 
 
645
  测试环境数据库
646
  公开项目的轻量级共享数据库
647
  Hugging Face Space 内部应用数据库
648
+ AI 生成文件索引系统
649
+ 用户文件索引系统
650
  ```
651
 
652
  不适合:
 
655
  高并发生产数据库
656
  金融交易核心数据库
657
  强一致性要求极高的数据库
658
+ 需要专业数据库 SLA 的业务
659
+ 需要大量公网 PostgreSQL 长连接的业务
660
  ```
661
 
662
  ---
663
 
664
+ ## 17. 默认连接信息
665
 
666
+ Adminer Web:
667
 
668
  ```text
669
+ https://你的-space.hf.space
670
  ```
671
 
672
+ PostgreSQL:
 
 
673
 
674
+ ```text
675
+ Host: 127.0.0.1
676
+ Port: 5432
677
+ User: admin
678
+ Database: appdb
679
+ Data Directory: /home/user/pgdata
680
+ Backup Directory: /data/backups
681
+ User File Directory: /data/files
682
  ```
683
 
684
+ 注意:`127.0.0.1:5432` 是容器内部地址,主要给 Adminer 或同容器内应用使用。外部项目不建议直接连接该端口,推荐通过 API Gateway 或受控后端访问数据库。
685
 
686
  ---
687
 
688
+ ## 18. 重要说明
689
 
690
+ 本项目基于官方 PostgreSQL Docker 镜像:
 
 
691
 
692
  ```text
693
+ postgres:17
 
 
694
  ```
695
 
696
+ 部署时不需要拉取 `docker-library/postgres` 源码,只需要在 Dockerfile 中使用:
697
 
698
+ ```dockerfile
699
+ FROM postgres:17
700
  ```
701
 
702
+ 即可。
 
 
 
 
 
703
 
704
+ 本项目的关键设计是:
705
 
706
  ```text
707
+ PostgreSQL 运行数据目录:/home/user/pgdata
708
+ 挂载大磁盘:/data
709
+ 数据库备份:/data/backups
710
+ 用户文件:/data/files
711
+ 导出文件:/data/exports
712
+ 生成文件:/data/generated
 
 
 
 
 
 
 
 
 
 
 
713
  ```
714
 
715
+ 这样可以避免 PostgreSQL 直接在挂载 Bucket 上运行时出现文件权限或文件系统兼容问题,同时又能利用大容量挂载磁盘保存备份和业务文件。