# gallery.fukun.net

基于 [Photoview](https://github.com/photoview/photoview) 定制的个人相册，部署在腾讯云 `62.234.90.54`。

---

## 访问

| 地址 | 说明 |
|------|------|
| `https://gallery.fukun.net` | 管理后台（需登录） |
| `https://cdn.fukun.net/gallery/photos/...` | CDN 公开原图 |

---

## 定制项（与上游 Photoview 的差异）

- **品牌** — 左上角 FK 书法 logo，页面标题 `Gallery.FuKun.Net`
- **外观** — 纯黑背景 (`#000`)，菜单图标改为极简线条，顶栏 64px 高与主站一致
- **字体** — iA Writer Quattro S + Noto Sans SC（与主站 fukun.net 一致）
- **交互** — 点击图片打开侧边栏详情（去掉全屏预览），手机端点遮罩层关闭
- **无 Docker** — Go 二进制 + systemd，SQLite 单文件数据库
- **人脸识别** — 已关闭（`PHOTOVIEW_DISABLE_FACE_RECOGNITION=1`）
- **CDN** — 仅公开原图走 `cdn.fukun.net`；管理界面图片直连（需鉴权 cookie，无法跨域走 CDN）

---

## 服务器

| 项目 | 详情 |
|------|------|
| 服务器 | 腾讯云轻量 · 北京七区 |
| 公网 IP | `62.234.90.54` |
| 系统 | Ubuntu 24.04 LTS · 4核4G · SSD 40G + 20G |
| Go | 1.22.2（系统自带）→ 编译时自动下载 toolchain 1.26.0 |
| Node | v22.22.2 |
| Nginx | `/etc/nginx/` · 80/443 |
| SSL | 腾讯云证书 · `/etc/nginx/ssl/` |

### 架构

```
                      Internet
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   fukun.net      gallery.fukun.net  pwd.fukun.net
   (Hugo 博客)     (Photoview)       (Vaultwarden)
   直接访问          直接访问           直接访问
        │                │
   ┌────┴────┐     ┌────┴────┐
   │         │     │         │
  HTML    静态资源  页面/API   /photos/*
  不缓存  加了缓存头  proxy    serve 文件
          │          │         │
          │          │         │
   ┌──────┴──────────┴─────────┴──────┐
   │          cdn.fukun.net          │  ← 腾讯云 CDN
   │    /blog/* → fukun.net          │     只代理静态资源
   │    /gallery/* → gallery...net   │     主站不经过 CDN
   └─────────────────────────────────┘
```

`gallery.fukun.net` 由 Nginx 统一接入，按路径分流：

| 路径 | 行为 |
|------|------|
| `/photos/*` | 直接 serve 原图（CDN 回源口，加 CORS + 缓存头） |
| `/assets/*` | 缓存 30 天（JS/CSS/字体，文件名带 hash） |
| `/*` | 反向代理到 `127.0.0.1:8000`（Photoview） |

---

## 目录结构

### 服务器（`/home/gallery/`）

```
/home/gallery/
├── photoview-src/          # 源码 + 编译产物（git 管理）
│   ├── api/
│   │   ├── .env            # 运行时环境变量
│   │   └── photoview       # Go 二进制（38MB）
│   └── ui/
│       └── dist/           # 前端构建产物
├── photos/                 # 相片库根目录
├── data/
│   ├── photoview.db        # SQLite 数据库
│   └── media-cache/        # 缩略图缓存
└── go/                     # Go 模块缓存（449MB，运行时不需要）
```

### 各目录职责

| 目录 | 谁创建 | 生命周期 | 备份？ |
|------|--------|----------|--------|
| `photoview-src/` | 手动上传 | 持久，更新时重传/`git pull` | 不需要（git 管理） |
| `photos/` | 手动上传 | 持久 | ✅ **核心数据，必须备份** |
| `data/photoview.db` | Photoview 首次启动 | 持久 | ✅ 备份（单文件直接 cp） |
| `data/media-cache/` | Photoview 扫描时 | 可重建 | 可选（丢了能重新生成） |
| `go/` | `go mod download` | 可重建 | 不需要 |

---

## 本地开发

> 后端依赖 Linux C 库（dlib/libheif/ImageMagick），无法在 Windows 本地运行。
> 只能改前端代码，API 指向生产环境。

```bash
git clone ssh://git@fukun.net/data/git-repos/gallery.git
cd ui

cat > .env << EOF
REACT_APP_API_ENDPOINT=https://gallery.fukun.net/api/
REACT_APP_BUILD_VERSION=dev
REACT_APP_BUILD_DATE=$(date -u +%Y-%m-%d)
REACT_APP_BUILD_COMMIT_SHA=local
EOF

npm ci
npm run dev          # localhost:1234，API 连生产服务器
```

改完前端后，构建 + 部署到服务器（见下文「部署」）。

---

## 运行时配置

### systemd — `/etc/systemd/system/photoview.service`

| 环境变量 | 值 |
|----------|-----|
| `PHOTOVIEW_DATABASE_DRIVER` | `sqlite` |
| `PHOTOVIEW_SQLITE_PATH` | `/home/gallery/data/photoview.db` |
| `PHOTOVIEW_LISTEN_IP` | `127.0.0.1` |
| `PHOTOVIEW_LISTEN_PORT` | `8000` |
| `PHOTOVIEW_SERVE_UI` | `1` |
| `PHOTOVIEW_UI_PATH` | `/home/gallery/photoview-src/ui/dist` |
| `PHOTOVIEW_MEDIA_CACHE` | `/home/gallery/data/media-cache` |
| `PHOTOVIEW_DISABLE_FACE_RECOGNITION` | `1` |
| `LD_LIBRARY_PATH` | `/usr/local/im7/lib` |

### Nginx — `/etc/nginx/sites-enabled/gallery.fukun.net`

```nginx
server {
    listen 80;
    server_name gallery.fukun.net cdn.fukun.net;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name gallery.fukun.net cdn.fukun.net;

    ssl_certificate     /etc/nginx/ssl/gallery.fukun.net_bundle.crt;
    ssl_certificate_key /etc/nginx/ssl/gallery.fukun.net.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    client_max_body_size 4G;

    # 相片直出（CDN 回源）
    location /photos/ {
        alias /home/gallery/photos/;
        add_header Access-Control-Allow-Origin "*" always;
    }

    # 静态资源
    location /assets/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Photoview
    location / {
        add_header Access-Control-Allow-Origin "https://gallery.fukun.net" always;
        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
        add_header Access-Control-Allow-Credentials "true" always;

        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}
```

### SSL 证书

腾讯云证书，`/etc/nginx/ssl/gallery.fukun.net_bundle.crt` + `gallery.fukun.net.key`。

---

## 部署（从零或重装）

### 1. 系统依赖

```bash
sudo apt update
sudo apt install -y \
  g++ libheif-dev libdlib-dev libjpeg-dev \
  libblas-dev liblapack-dev libmagic-dev \
  ffmpeg git wget curl

# exiftool（EXIF 解析，启动必须）
sudo apt install -y exiftool
```

### 2. ImageMagick 7（关键）

> Ubuntu 24.04 只有 IM6，Photoview 的 Go 绑定 `imagick.v3` 依赖 IM7，必须源码编译。

```bash
tar xzf ImageMagick-7.1.1-47.tar.gz
cd ImageMagick-7.1.1-47
./configure --prefix=/usr/local/im7 --with-quantum-depth=16 --disable-docs --disable-static
make -j4
sudo make install
```

### 3. libcblas 兼容

> Ubuntu 24.04 把 CBLAS 合并进了 BLAS，但 dlib 的 linker 显式查找 `-lcblas`。

```bash
sudo ln -sf /usr/lib/x86_64-linux-gnu/libblas.so /usr/lib/x86_64-linux-gnu/libcblas.so
```

### 4. 上传源码 & 构建

```bash
# 本地打包上传
tar --exclude='.git' -czf pv-src.tar.gz .
scp pv-src.tar.gz ubuntu@62.234.90.54:/tmp/

# 服务器解压
sudo mkdir -p /home/gallery/photoview-src
sudo tar -xzf /tmp/pv-src.tar.gz -C /home/gallery/photoview-src
sudo chown -R gallery:gallery /home/gallery/photoview-src
```

**构建前端：**

```bash
sudo -u gallery bash -c "
cd /home/gallery/photoview-src/ui
# REACT_APP_API_ENDPOINT 必须用完整 URL，否则 new URL() 报 Invalid URL
cat > .env << ENDENV
REACT_APP_API_ENDPOINT=https://gallery.fukun.net/api/
REACT_APP_BUILD_VERSION=2.0.0-manual
REACT_APP_BUILD_DATE=$(date -u +%Y-%m-%d)
REACT_APP_BUILD_COMMIT_SHA=fukun-gallery
ENDENV
npm ci
npm run build
"
```

**构建后端：**

```bash
sudo -u gallery bash -c "
export PKG_CONFIG_PATH=/usr/local/im7/lib/pkgconfig
export CGO_ENABLED=1
cd /home/gallery/photoview-src/api

go mod download

# 修复 go-face（删 -lcblas 避免重复链接）
FACE=\$(find \$(go env GOMODCACHE) -path '*go-face*' -name face.go)
sudo chmod u+w \"\$FACE\"
sed -i 's/-lcblas//g' \"\$FACE\"

go build -v -o photoview .
"
```

### 5. systemd 服务

```bash
sudo mkdir -p /home/gallery/{photos,data/media-cache}
sudo chown -R gallery:gallery /home/gallery/data

sudo tee /etc/systemd/system/photoview.service << 'EOF'
[Unit]
Description=Photoview Gallery Server
After=network.target

[Service]
Type=simple
User=gallery
Group=gallery
WorkingDirectory=/home/gallery/photoview-src/api
ExecStart=/home/gallery/photoview-src/api/photoview
Restart=on-failure
RestartSec=5

NoNewPrivileges=yes
PrivateTmp=yes

Environment=PHOTOVIEW_DATABASE_DRIVER=sqlite
Environment=PHOTOVIEW_SQLITE_PATH=/home/gallery/data/photoview.db
Environment=PHOTOVIEW_LISTEN_IP=127.0.0.1
Environment=PHOTOVIEW_LISTEN_PORT=8000
Environment=PHOTOVIEW_SERVE_UI=1
Environment=PHOTOVIEW_UI_PATH=/home/gallery/photoview-src/ui/dist
Environment=PHOTOVIEW_MEDIA_CACHE=/home/gallery/data/media-cache
Environment=PHOTOVIEW_DISABLE_FACE_RECOGNITION=1
Environment=LD_LIBRARY_PATH=/usr/local/im7/lib

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now photoview
```

验证：

```bash
curl -s http://127.0.0.1:8000/api/graphql \
  -X POST -H 'Content-Type: application/json' \
  -d '{"query":"{ siteInfo { initialSetup } }"}'
# {"data":{"siteInfo":{"initialSetup":true}}}
```

### 6. SSL 证书 & Nginx

上传证书（`gallery.fukun.net.key` + `gallery.fukun.net_bundle.crt`）到 `/etc/nginx/ssl/`，然后创建上文 Nginx 配置并 reload：

```bash
sudo nginx -t && sudo nginx -s reload
```

---

## Ubuntu 24.04 特有问题

| 问题 | 原因 | 解决 |
|------|------|------|
| `MagickWand.h: No such file` | 24.04 只有 IM6，Photoview 依赖 IM7 | 源码编译 IM7 到 `/usr/local/im7` |
| `cannot find -lcblas` | 24.04 把 CBLAS 合并进 BLAS | `ln -sf libblas.so libcblas.so` |
| `exiftool not found` → panic | 启动必须有 exiftool | `apt install exiftool` |
| go-face `-lcblas` 重复链接 | go-face 内部也声明了 | `sed -i 's/-lcblas//g'` |
| go module cache 只读 | `go mod download` 文件只读 | `sudo chmod u+w` 后再改 |
| `new URL('/api/graphql')` 报 Invalid URL | 相对路径无法构造 URL | `REACT_APP_API_ENDPOINT` 用完整 URL |

---

## CDN 配置

统一加速域名 `cdn.fukun.net`，按路径回源：

```
cdn.fukun.net
├── /blog/*    → 回源 fukun.net（博客静态资源）
└── /gallery/* → 回源 gallery.fukun.net/photos/（相册原图）
```

| 配置项 | 值 |
|--------|-----|
| 加速域名 | `cdn.fukun.net` |
| 回源协议 | HTTPS |
| 回源 HOST | 留空（自动用源站域名） |

**注意：** CDN 只加速公开的静态文件。管理界面里的图片需要鉴权 cookie，不能走 CDN，仍直连 `gallery.fukun.net`。Hugo 博客嵌入原图时用 `https://cdn.fukun.net/gallery/photos/xxx.jpg`。

---

## 维护

### 状态

```bash
sudo systemctl status photoview
sudo journalctl -u photoview -f
```

### 更新前端

```bash
scp -r ui/src ui/public ubuntu@62.234.90.54:/tmp/pv-ui/
ssh ubuntu@62.234.90.54 '
  sudo cp -r /tmp/pv-ui/* /home/gallery/photoview-src/ui/
  sudo chown -R gallery:gallery /home/gallery/photoview-src/ui
  sudo -u gallery bash -c "cd /home/gallery/photoview-src/ui && npm ci && npm run build"
  sudo systemctl restart photoview
'
```

### 更新后端

```bash
ssh ubuntu@62.234.90.54 '
  cd /home/gallery/photoview-src/api
  export PKG_CONFIG_PATH=/usr/local/im7/lib/pkgconfig CGO_ENABLED=1
  sudo -u gallery go build -o photoview .
  sudo systemctl restart photoview
'
```

### 备份

```bash
# 数据库
sudo cp /home/gallery/data/photoview.db /opt/backup/photoview_$(date +%Y%m%d).db

# 上传照片
scp *.jpg ubuntu@62.234.90.54:/tmp/pv-photos/
ssh ubuntu@62.234.90.54 'sudo mv /tmp/pv-photos/* /home/gallery/photos/ && sudo chown -R gallery:gallery /home/gallery/photos/'
```

---

## 端口汇总

| 端口 | 用途 | 公网 |
|------|------|------|
| 22 | SSH | ✅ |
| 80/443 | Nginx 全站 | ✅ |
| 8000 | Photoview | ❌ 127.0.0.1 |
| 8080 | Vaultwarden | ❌ 127.0.0.1 |
| 17581 | OpenClaw | ❌ |

---

## 初始化

1. 浏览器访问 `https://gallery.fukun.net`
2. 创建管理员账号
3. **Photo Path** 填 `/home/gallery/photos`
4. 上传相片后，Settings → Scan All

---

## 仓库

```
ssh://git@fukun.net/data/git-repos/gallery.git
```

服务器 `/data/git-repos/gallery.git`（bare），推送到 `master`。