HomeLab 折腾记：Authentik + Music-Tag-Web 完美部署实践

碎碎念：为了那 3000 多首歌的“脸面”

事情的起因很简单：作为一名强迫症晚期患者，看着本地音乐库里那 3000 多首歌要么没封面，要么歌词乱七八糟，实在难以忍受。我决定部署 Music-Tag-Web 来给它们统一“整容”。

为了安全，我坚持要把这个服务挂在我的 Authentik 统一认证网关后面。但没想到，这开启了一段长达数小时、涉及容器架构与 Nginx 匹配机制的硬核排障之旅。

第一步：Docker Compose 部署

我将持久化数据统一放在 /opt/music_tag_config 下。为了让 Authentik 的 Outpost 能够顺利打通网络，我将其加入了已有的 authentik-internal 外部网络。

这里有一个非常容易踩坑的细节：由于需要挂载宿主机的物理音乐库 /DATA/openlistdata/Music，如果容器内的运行用户与宿主机目录权限不一致，刮削后保存标签时绝对会报“权限拒绝”的错误

docker-compose.yml 配置：

YAML

version: '3.8'

services:
  music-tag-web:
    image: xhongc/music_tag_web:latest
    container_name: music-tag-web
    # 注释掉自带重启策略，交由下面的 Systemd 全权接管
    # restart: unless-stopped
    ports:
      - "127.0.0.1:8001:8001"
    volumes:
      - /opt/music_tag_config:/app/data
      - /DATA/openlistdata/Music:/app/media
    networks:
      - default
      - authentik-internal

networks:
  authentik-internal:
    external: true

第二步：Systemd 守护进程——让服务“稳如老狗”

虽然 Docker 提供了 restart: unless-stopped，但我更有“系统洁癖”，希望它能像标准服务一样被管理。于是我编写了 Systemd Unit 文件。

操作指令：

1. 创建文件：sudo vim /etc/systemd/system/music-tag.service

[Unit]
Description=Music Tag Web Service with Docker Compose
Requires=docker.service
After=docker.service authentik.service

[Service]
Type=oneshot
RemainAfterExit=yes
# 这里的路径请务必指向你 docker-compose.yml 所在的真实目录
WorkingDirectory=/opt/music_tag_config
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target                          

1. 启用并启动：

   Bash

   sudo systemctl daemon-reload
   sudo systemctl enable music-tag.service
   sudo systemctl start music-tag.service
   

   

第三步：配置 Authentik 认证网关 (不可或缺的一环)

既然要把服务藏在 Authentik 后面，我们必须先在 Authentik 的 Web UI 中为它创建一个“通行证”。

第四步：硬核排障——404 认床病与路径劫持

这是本次部署最精华的部分。当我配置好 Nginx 代理后，通过域名访问竟然白屏了！JS 和 CSS 资源全部 404。

排查发现两个巨坑：

1. 路径重名劫持：Authentik 自身也使用了 /static/ 路径，当 Proxy 转发时，Authentik 可能会把请求拦下来在自己肚子里找，找不到就报错。

2. 后端“认床病”：容器内的 Python 框架只认 127.0.0.1。当你带着 music-tag.yanchang.cc 的域名去访问时，它会因为不安全而拒绝提供静态文件。

终极解法：动静分离 + Host 洗脑 我为该服务配置了独立的 Nginx Server 块，强制在 /static/ 路径下清洗 Host 标头，伪装成本地访问绕过验证。

/etc/nginx/sites-available/music-tag.conf：

Nginx

server {
    # 监听 9001 端口并启用 SSL
    listen 9001 ssl;
    listen [::]:9001 ssl;

    server_name music-tag.yanchang.cc;

    # SSL 证书路径 (根据你之前的配置)
    ssl_certificate     /etc/nginx/ssl/www.yanchang.pem;
    ssl_certificate_key /etc/nginx/ssl/www.yanchang.key;

    # SSL 协议及安全优化
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 上传大小限制 (适配音乐文件上传)
    client_max_body_size 100M;

    # ========================================================
    # 1. 静态资源绿色通道：绕过 Authentik 解决路径冲突和 404
    # ========================================================
    location /static/ {
        # 核心：伪装 Host 为本地，治好后端的“认床病”
        proxy_set_header Host 127.0.0.1:8001;

        # 直接透传给 music-tag-web 容器
        proxy_pass http://127.0.0.1:8001/static/;

        # 性能优化：开启缓存
        expires 7d;
        add_header Cache-Control "public, no-transform";

        # 传递真实 IP 
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # ========================================================
    # 2. 核心业务逻辑：交给 Authentik 严密保护
    # ========================================================
    location / {
        # 指向 Authentik 的 Outpost 端口
        proxy_pass http://127.0.0.1:9000;

        # 标准代理头：带端口的 Host 必不可少
        proxy_set_header Host $http_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;

        # WebSocket 支持 (Authentik 必须)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时设置
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
        proxy_read_timeout 300;
    }
}

最后，通过软连接启用配置：

Bash

sudo ln -s /etc/nginx/sites-available/music-tag.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

结语

当紫色的界面顺滑加载出来的那一刻，所有的折腾都值了。现在，3000 多首歌的刮削工作已经正式开始。

经验教训：永远不要低估永远不要忽视 Nginx location 匹配的优先级。

实战填坑——应对大批量处理 BUG

在实际刮削那 3000 多首歌的过程中，我发现当前的 Music-Tag-Web 项目存在一个性能 BUG：如果一次性选中的歌曲数量过多，程序会因为资源消耗或超时导致中断报错。

我的应对策略：

• 小批量多次：最稳妥的方法是分批处理，每次选中几百首歌。

• 人工监守：如果一定要“全选”进行大批量处理，必须人工守在屏幕前。

• 禁断操作：在大批量处理任务运行期间，绝对不要在 Web 界面进行任何其他点击操作，否则极易触发崩溃。

• 及时续接：一旦观察到报错中断，不要慌，刷新页面并重新选择那些“未处理”的歌曲再次开始。
  

运维小贴士：慎用 mv 的“暴力模式” 在整理 3000 多首歌的过程中，文件的去重和归档是个细致活。我习惯先用 mv -n（no-clobber）进行初步移动，它像个严谨的哨兵，告诉我哪些歌已经在库里“占了坑”，避免了我不小心把辛苦刮削好的精美版本覆盖成旧版本，或者重复搬运。这种“安全第一”的操作习惯，是管理海量数据的基本功。