# 看板对外访问与单一口令鉴权 交付说明

时间：2026-06-12
阶段：阶段二（让运营能真正打开用）

## 1. 访问地址

```text
https://wwyl.yipeng.online/goods-ledger/dashboard/
```

- 裸路径 `https://wwyl.yipeng.online/goods-ledger` 会 302 跳到上面。
- 需 HTTP Basic Auth（单一口令），用户名 `wwyl`（2026-06-12 应用户要求由 ledger 改为好记账号，口令由用户口头指定）。

## 2. 方案

一个域名多子路径反代的现有模式下，新增唯一前缀 `/goods-ledger/`：

- 复用现有域名 `wwyl.yipeng.online` 的 HTTPS 证书，**不需 DNS / 新证书**。
- nginx 新增 location 反代到后端 `127.0.0.1:8791` 并剥前缀，后端无改动。
- Basic Auth 加在 nginx 该 location 上（口令文件 `/etc/nginx/htpasswd-goods-ledger`），后端写入层仍另有 `X-Ledger-API-Key`，形成双层。

### 为什么必须用子路径前缀（而非根路径）

勘察发现现有 `hermes-openwebui` 配置有正则 location 已占用根路径 `/api/`、`/assets/`（反代到 19119）。若把台账 API 放根路径会撞车。因此：

- nginx 用 `location ^~ /goods-ledger/`（`^~` 确保不被 hermes 正则截走）。
- 前端必须重新构建到 `/goods-ledger/` 前缀下，否则资源/API 仍指向被占用的根路径。

## 3. 实施内容

### nginx

- 新增 snippet：`/etc/nginx/snippets/goods-ledger-locations.conf`（项目留档 `deploy/nginx-goods-ledger-locations.conf`）。
- 在 `/etc/nginx/sites-available/wwyl.yipeng.online-ssl` 的 443 server 块加一行 `include`（原文件已备份 `*.bak-20260612_150040`）。
- `nginx -t` 通过后 `systemctl reload nginx`（优雅重载，现有服务无中断）。

### 口令

- `openssl passwd -apr1` 生成，写入 `/etc/nginx/htpasswd-goods-ledger`（`root:www-data 640`，照搬 hermes 模式）。
- 用户名 `wwyl`（初版为 ledger+强随机口令，后按用户要求改为好记口令）。

### 前端

- 云端 `/srv/goods-ledger/frontend/dist` 重新构建部署，旧 dist 备份 `dist.bak-20260612_145914`。
- 构建参数：

```bash
VITE_BASE_PATH=/goods-ledger/dashboard/ VITE_LEDGER_API_BASE=/goods-ledger npm run build
```

## 4. 验证

外部视角（从 NAS 经公网域名）：

```text
无口令 /goods-ledger/dashboard/      => 401
带口令 /goods-ledger/dashboard/      => 200 text/html
带口令 /goods-ledger/api/dashboard/overview => 200 json(真实数据)
/goods-ledger                        => 302 -> /goods-ledger/dashboard/
```

未影响现有服务：

```text
根 /api/            => 401 realm="Hermes Dashboard"（仍走19119，未撞车）
/hermes-dashboard/  => 401（自有口令，不变）
根 /                => 200（首页不变）
/goods-ledger/      => realm="Goods Ledger"（独立口令）
```

## 5. 边界与后续

- 当前是只读看板 + 单一共享口令，适合内部少数人先用。
- 若要按人分账号 / 审计谁访问，下一步可换成多账号或接 SSO。
- 口令轮换：更新 `/etc/nginx/htpasswd-goods-ledger` 后 `nginx -s reload`，无需改其他。
- 回滚：移除 site 配置里的 include 行（或恢复 `.bak`），`nginx -t && reload` 即可下线入口。