初始化蓝鸟文件快递柜源码与部署文档

2026-10-05 23:41:07 +08:00
commit 5643d22242
@@ -0,0 +1,140 @@
+# Linux amd64 部署
+
+前端与SQLite已包含在二进制中，运行无需Go、Node.js、PostgreSQL或Valkey。脚本用于有systemd的Linux amd64/x86_64主机，需root或sudo，以及shadow、util-linux和coreutils（useradd、groupadd、getent、runuser、flock、install等）。
+
+## 已有安装：添加公网HTTP和独立内网入口
+
+本节以蓝鸟服务器192.168.1.10、独立反向代理和主入口 `https://files.example.com` 为例。将新版发布包与SHA256SUMS上传至工作目录，解压到一个新的空目录：
+
+```sh
+sha256sum -c SHA256SUMS
+mkdir bluebird-release-new
+tar -xzf bluebird-linux-amd64.tar.gz -C bluebird-release-new
+cd bluebird-release-new
+sudo ./upgrade.sh --lan-url http://192.168.1.10:8080 \
+  --access-url http://files.example.com
+```
+
+脚本先校验候选配置，随后自动停服、备份、更新程序和配置、执行完整性检查、启动服务。保留原管理员密码、数据库、文件、密钥、取件码、后台策略和其他配置；不会重新初始化。旧程序、原配置和一致性数据归档保留在 `/opt/bluebird/backups/upgrade-时间-进程号/`。备份含敏感信息，应复制到独立备份位置并按自己的容量策略清理。更新失败会恢复旧程序及配置；当前数据库结构版本仍为1。
+
+升级后以下入口同时可用：
+
+- 内网：`http://192.168.1.10:8080`，无需解析公网域名。
+- 公网HTTP：`http://files.example.com`，由反向代理提供80端口。
+- 公网HTTPS：`https://files.example.com`，由反向代理提供443端口和有效证书。
+- 各入口的管理后台：在对应地址后添加 `/#/admin`。
+
+内网入口直接连接蓝鸟。公网入口仍需域名正确解析到代理、代理转发到 `192.168.1.10:8080`；程序不能绕过公网DNS故障。主机网络/防火墙需允许内网客户端和代理连接8080。HTTP传输不加密；它可以正常上传、取件和管理登录。
+
+## 首次安装
+
+已有安装使用上面的upgrade.sh；install.sh不会覆盖已有目录或同名服务。首次部署在发布包解压目录运行：
+
+```sh
+sudo ./install.sh --url https://files.example.com \
+  --access-url http://files.example.com \
+  --lan-url http://192.168.1.10:8080 --encrypt --no-start
+sudo systemctl daemon-reload
+sudo systemctl enable --now bluebird.service
+```
+
+将域名、IP换成实际值。脚本提示输入两次管理员密码，账号admin，没有默认密码。`--encrypt`启用新上传文件的服务端落盘加密；`--no-start`安装并初始化，但暂不启动。也支持单独的公网HTTP域名：`--url http://files.example.com`，无需在域名后写8080，后端默认监听127.0.0.1:8080。纯内网部署可用 `--url http://192.168.1.10:8080 --lan-http`。
+
+默认目录：
+
+```text
+/opt/bluebird/
+├── bluebird                    # 二进制，前端内嵌
+├── config.toml                 # root:bluebird / 0640
+├── bluebird.service            # 服务定义副本
+├── THIRD_PARTY_NOTICES.txt
+├── backups/                    # 升级时生成的备份
+└── var/                        # bluebird:bluebird / 0700，数据库、对象、密钥
+```
+
+程序与配置由root管理，服务以bluebird账号运行，仅写var；systemd定义安装在 `/etc/systemd/system/bluebird.service`。不修改代理、DNS、防火墙。自动化初始化可用 `BLUEBIRD_ADMIN_PASSWORD` 环境变量，密码不写入配置或服务定义。
+
+## 多入口配置
+
+上述升级命令得到的相关配置为：
+
+```toml
+listen = "192.168.1.10:8080"
+public_url = "https://files.example.com"
+access_urls = ["http://192.168.1.10:8080", "http://files.example.com"]
+secure_cookies = true
+allow_lan_http = true
+# 将下例替换成反向代理机器的实际IP，保留原有需要信任的代理：
+# trusted_proxies = ["192.168.1.20/32"]
+```
+
+`public_url`是默认入口，`access_urls`增加精确允许的入口，最多16个，地址只包含协议、域名/IP和可选端口，不带路径。`secure_cookies`与默认入口协议一致；其他入口按实际协议自动设置cookie。HTTP与HTTPS同时使用同一域名时，HTTP cookie采用独立名称，避免覆盖Secure cookie。不同入口的浏览器会话和登录可能独立，文件和取件码在所有入口共用，下载额度与期限不会翻倍。
+
+生成分享时默认采用当前访问入口，可在弹窗中选择其他入口；链接及二维码一起更新，取件码保持相同。内网寄件无需访问公网域名，即使公网DNS不可用也可完成全过程。
+
+异机代理的真实IP/CIDR需要加入 `trusted_proxies`，使公网访客IP限额与审计准确。脚本不会猜测代理IP，升级保留旧值；不要设置为整个互联网或任意来源。配置修改后重启服务。程序拒绝未知Origin及相互矛盾的来源头，不使用无限制CORS。
+
+## 代理同时提供HTTP和HTTPS
+
+在反向代理机器上使用下例（域名与蓝鸟配置一致）：
+
+```caddyfile
+{
+    auto_https disable_redirects
+}
+http://files.example.com {
+    reverse_proxy 192.168.1.10:8080 {
+        flush_interval -1
+    }
+}
+https://files.example.com {
+    reverse_proxy 192.168.1.10:8080 {
+        flush_interval -1
+    }
+}
+```
+
+两个明确的站点块分别提供HTTP与HTTPS；不要仅使用自动将HTTP跳转到HTTPS的配置。Nginx等代理同样需将80和443的请求转发至这个后端，并转发Host、X-Forwarded-Host、X-Forwarded-Proto、X-Forwarded-For及前端的X-Bluebird-Origin。应避免上传磁盘缓冲、下载内容缓存，并配置匹配文件限制的请求大小及超时。不要将var配置成代理静态目录。
+
+证书与公网DNS在代理侧管理；代理必须能连接192.168.1.10的8080端口。若使用其他软件管理代理，在该软件中为HTTP和HTTPS各开启对应入口。
+
+## 检查与日常操作
+
+```sh
+sudo systemctl status bluebird --no-pager
+sudo ss -lntp | grep ':8080'
+sudo journalctl -u bluebird -n 50 --no-pager
+```
+
+应看到监听192.168.1.10:8080。没有curl也可直接在浏览器打开 `http://192.168.1.10:8080/api/v1/health`，预期 `{"ready":true}`，然后访问首页测试寄件和取件。检查公网HTTP和HTTPS时分别使用两个协议，不能依赖代理自动跳转；管理页均在 `/#/admin`。
+
+默认文件预算9GiB、数据预算10GiB、卷最少保留1GiB；单文件100MiB、每批10个、总500MiB。管理员在“服务策略”“容量与保留”修改额度、期限、下载次数和审计规则。初始化后的后台设置持久化于SQLite，编辑TOML的初始值不会覆盖。
+
+`--prefix`可指定其他已有安装目录；默认 `/opt/bluebird`。`--listen`覆盖监听地址，`--lan-url`未指定listen时自动绑定其IP和端口；独立账号监听1024至65535端口，公网80/443由代理负责。`upgrade.sh --no-start`用于手动停服后的离线升级，完成后暂不启动；必须先确认旧服务已停止，数据锁会拒绝并行维护。首次安装路径不能包含空格或位于/home、/root，systemd保护这些目录。
+
+## 备份和密码重置
+
+全部维护CLI需先停服，与服务共用独占数据锁：
+
+```sh
+sudo install -d -o bluebird -g bluebird -m 0700 /opt/bluebird/backups
+sudo systemctl stop bluebird
+sudo runuser -u bluebird -- /opt/bluebird/bluebird backup \
+  --config /opt/bluebird/config.toml \
+  --output /opt/bluebird/backups/bluebird-backup.tar.gz
+sudo systemctl start bluebird
+```
+
+备份包含数据库、文件、配置和密钥，不能只复制运行中的SQLite主文件或只备份对象。升级保留旧取件码；执行restore恢复历史快照时旧分享及会话失效，管理员需逐项审核重新发布，规则见 [operations.md](operations.md)。
+
+```sh
+sudo systemctl stop bluebird
+sudo runuser -u bluebird -- /opt/bluebird/bluebird reset-password --config /opt/bluebird/config.toml
+sudo systemctl start bluebird
+```
+
+只校验配置、不打开数据库：
+
+```sh
+sudo /opt/bluebird/bluebird validate-config --config /opt/bluebird/config.toml
+```