xiaoju-cloud / docs /self-host-postgres.md
langhua1998's picture
Deploy xiaoju-cloud 3e06b58
264f9da verified
|
Raw History Blame Contribute Delete
3.83 kB
# 小橘云盘:自建 PostgreSQL 设计要求
## 背景
- 云盘服务(langhua98/xiaoju-cloud,Go)现在跑在 Hugging Face Space,数据库用 Neon 免费版。
- 2026-11-10 Neon 免费额度用完,服务启动时连不上库就退出,云盘全部 503。
- 文件内容存在 Telegram 频道,不在数据库里;数据库存文件名、目录、令牌、分块索引等元数据。
- 数据库每天自动加密备份,置顶在 Telegram 主频道和备份频道。
## 目标
在北卡家里一台常开的电脑上跑 PostgreSQL,替代 Neon,并恢复数据。
## 数据库要求
- PostgreSQL 16 或 17(项目没有用任何扩展,标准版就行)。
- 一个专用数据库和用户,比如库名 `xiaoju`、用户 `xiaoju`,用强密码。不要用 postgres 超级用户给云盘连。
- 表由云盘自己建:服务启动时自动执行 `migrations/` 里的迁移(目前到 0019),不用手动建表。
- 连接串通过环境变量 `XIAOJU_DATABASE_URL` 给云盘,格式:
`postgres://xiaoju:<密码>@<主机>:<端口>/xiaoju?sslmode=require`
- 数据放在有空间的磁盘上,做好本机定期备份(`pg_dump` 每天一次即可,云盘自己也会往 Telegram 备份)。
## 电脑要求
- 24 小时开机,关掉系统睡眠或休眠;断电后能自动开机、自动启动 PostgreSQL(设为系统服务)。
- 稳定的家庭网络。
## 网络:两种方案选一种
### 方案 A(推荐):整个云盘服务也搬到这台电脑
- 云盘服务和 PostgreSQL 都在本机,数据库只监听 `127.0.0.1`,不对外。连接串用 `localhost`,可以 `sslmode=disable`。
- 用 Cloudflare Tunnel(或 Tailscale Funnel)把云盘的 HTTP 端口开到公网,不在路由器上开端口。
- 手机遥控要用 WebSocket(`/api/agent/v1/relay/ws`、视频流),隧道要支持 WebSocket(Cloudflare Tunnel 默认支持),而且空闲连接不能太快被掐(手机心跳最长约 9 分钟一次)。
- 云盘原来在 Hugging Face 上的环境变量和 secrets 都要搬过来(尤其是主密钥 `XIAOJU_MASTER_KEY` 和 Telegram 相关的那些),名字照 Hugging Face Space 设置页里的抄。主密钥丢了,备份和文件都解不开。
- 网址变了的话,手机 App、小橘推送、网页里配的云盘地址都要改。
### 方案 B:云盘留在 Hugging Face,只把数据库放家里
- Hugging Face 要能从公网连进 PostgreSQL,所以需要:
- 路由器转发一个非默认端口到 5432(或者用支持 TCP 的隧道);
- PostgreSQL 开 SSL(`ssl = on`),`pg_hba.conf` 只允许 `xiaoju` 用户用 `scram-sha-256` + SSL 连接;
- 家里公网 IP 会变的话,配一个动态域名(DDNS)。
- 把 Hugging Face Space 里的 secret `XIAOJU_DATABASE_URL` 换成新的连接串,然后重启 Space。
- 缺点:数据库直接暴露在公网,要盯紧安全。
## 恢复数据(两种方案都要做)
1. 建好空库和用户(不要提前建表)。
2. 用云盘自带的命令,从 Telegram 置顶备份恢复。环境变量要和线上一样(`XIAOJU_DATABASE_URL` 指向新库,加上主密钥和 Telegram 相关变量):
- `xiaoju dbrestore --check`:只下载、解密、检查,不写库,先跑这个确认备份完好;
- `xiaoju dbrestore`:恢复进空库(库里已有表会拒绝,不会覆盖)。
3. 启动云盘,确认能登录、能看到文件。
4. 会丢最后一次每日备份之后的改动(最多约 24 小时)。
## 完成后的检查
- 网页能登录,文件列表正常,能下载一个旧文件。
- `/api/agent/v1/relay` 能收发(手机遥控能用)。
- 重启电脑后,数据库和云盘都能自动起来。
具体做法(Windows,方案 A):[deploy/windows/README.md](../deploy/windows/README.md)。