gallery.fukun.net

基于 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 指向生产环境。

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

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. 系统依赖

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，必须源码编译。

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。

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

4. 上传源码 & 构建

# 本地打包上传
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

构建前端：

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
"

构建后端：

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 服务

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

验证：

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：

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。

---

维护

状态

sudo systemctl status photoview
sudo journalctl -u photoview -f

更新前端

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
'

更新后端

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
'

备份

# 数据库
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。