# OnboardX 双前端域名部署说明

## 1. 最终访问结构

- 员工入职：https://onboardx.cnzhyx.cn
- 后台管理：https://onboardx-admin.cnzhyx.cn
- 契约锁回调：https://onboardx-api.cnzhyx.cn/api/open/onboarding/qiyuesuo/callback
- 后端仍然只有一套，不需要复制数据库或部署第二套 API。

两个前端是同一份源码的不同构建结果：

- build:admin 生成完整后台，输出到 dist-admin。
- build:public 只生成员工填报、链接失效和 404 页面，输出到 dist-public。

员工域名的容器只转发 /api/open/onboarding/。任何 /api/sys/、/api/biz/ 或其他 API 都会直接返回 404。

## 2. 本次涉及的配置文件

- Dockerfile.admin：构建、运行完整后台前端。
- Dockerfile.public：构建、运行纯员工入职前端。
- admin.conf：后台前端容器内部 Nginx。
- public.conf：员工前端容器内部 Nginx，并限制公开 API。
- edge-domains.conf.example：服务器最外层三个 HTTPS 域名的参考配置。
- api-public-callback.conf.example：只单独配置 API 回调域名时的精简参考。

## 3. 上线前准备

### 3.1 DNS

在域名服务商处确保以下记录都指向同一台服务器公网 IP：

    onboardx.cnzhyx.cn
    onboardx-admin.cnzhyx.cn
    onboardx-api.cnzhyx.cn

### 3.2 HTTPS 证书

证书必须覆盖新域名 onboardx-admin.cnzhyx.cn。如果已有 *.cnzhyx.cn 通配符证书，可以继续使用。

### 3.3 后端容器服务名

两个前端容器内部配置默认访问：

    http://onboardx-api-svc:5566

因此两个前端容器必须与后端处于同一个 Docker 网络，并且后端在该网络中的名称或别名为 onboardx-api-svc。如果线上服务名不同，只修改 admin.conf 和 public.conf 中的 upstream 地址，不要改公开接口范围。

## 4. 构建两个前端镜像

在前端项目根目录执行：

    docker build -f Dockerfiles/Dockerfile.admin -t onboardx-admin-web:20260915 .
    docker build -f Dockerfiles/Dockerfile.public -t onboardx-public-web:20260915 .

VITE_PUBLIC_ONBOARDING_URL 是构建期配置，生产环境已经设置为：

    https://onboardx.cnzhyx.cn

以后如果更换员工域名，修改 .env.production 后必须重新构建后台镜像，不能只改 Nginx。

## 5. 启动两个前端容器

下面仅作为普通 Docker 示例；如果使用宝塔、Portainer、Kubernetes 或云平台，就在对应界面填写相同的镜像、端口和网络关系。

    docker run -d --name onboardx-admin-web --restart always --network onboardx-net -p 127.0.0.1:18081:80 onboardx-admin-web:20260915
    docker run -d --name onboardx-public-web --restart always --network onboardx-net -p 127.0.0.1:18082:80 onboardx-public-web:20260915

如果现有后端不在 onboardx-net，应让三个容器加入同一个已有网络。不要为了省事把后端所有端口直接暴露到公网。

## 6. 配置服务器最外层 Nginx

1. 复制 edge-domains.conf.example 到服务器 Nginx 的站点配置目录。
2. 把证书路径改为服务器上的真实路径。
3. 确认端口：
   - 18081 是后台前端。
   - 18082 是员工前端。
   - 15566 是后端映射到服务器本机的端口；如果后端没有映射该端口，应改为实际地址。
4. 执行 nginx -t 检查配置。
5. 检查通过后执行 nginx -s reload 平滑重载。

服务器最外层 Nginx 只负责域名、HTTPS 和转发。真正的公开 API 白名单在员工前端容器的 public.conf 内再次限制，形成两层保护。

## 7. 推荐发布顺序

1. 先完成 onboardx-admin.cnzhyx.cn 的 DNS 和证书。
2. 启动后台前端容器，确认新后台域名登录及业务功能正常。
3. 启动员工前端容器，但先不要发送新链接。
4. 将原来的 onboardx.cnzhyx.cn 切换到员工前端容器。
5. 打开一次员工域名，确认显示“入职链接无效”。
6. 从后台复制一条有效链接，用电脑和安卓手机各走一遍。
7. 最后确认契约锁回调仍然成功。

员工域名以前部署过后台 PWA。本次公开构建会发布一个自销毁 Service Worker，自动注销旧 PWA 并清理旧缓存。老手机第一次打开时可能自动刷新一次；若仍看到旧页面，关闭该页面后重新打开即可。

## 8. 安卓下载处理

- 普通桌面和 iOS 浏览器通过不携带后台凭证的文件流下载。
- 安卓及安卓 WebView 直接访问同域公开文件接口，避免 blob: 下载被系统 WebView 拦截。
- 安卓微信如果不支持文件接管，页面会提示用户点击右上角“在浏览器打开”后重新下载。
- 后台 PWA 的 Service Worker 不再拦截 /api/，所以文件接口不会错误回退成 index.html。

## 9. 上线验收清单

- 访问 https://onboardx.cnzhyx.cn/，只显示“入职链接无效”。
- 访问 /#/onboarding/fill 但不带 Token，自动进入链接无效页。
- 修改 Token 任意一个字符，提示链接不存在或无效。
- 公开域名访问 /api/sys/ 返回 404。
- 公开域名访问 /api/biz/ 返回 404。
- 公开域名不能出现后台登录页、菜单、员工档案或系统管理页面。
- 后台生成的员工链接始终以 https://onboardx.cnzhyx.cn 开头。
- onboardx-admin.cnzhyx.cn 的登录、上传、下载和业务操作正常。
- 安卓 Chrome、安卓微信、桌面浏览器均测试合同下载。
- 契约锁回调地址保持不变且能正常更新签署状态。

## 10. 回滚原则

后台前端和员工前端可以分别回滚到各自上一个镜像版本。不要把员工域名重新指向完整后台作为临时回滚方案，否则会重新暴露后台入口。若员工端出现故障，应只回滚 onboardx-public-web 镜像。