WorkBuddy私有化部署后管理控制台无法加载、API 404或OAuth回调失败，主因是DNS解析类型配置错误：控制台与API网关必须用A记录直连服务器IP，WAF/高防及CDN场景必须用CNAME，OAuth和Webhook子域可选A或CNAME但不可混用，静态资源域名必须CNAME接入CDN。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成WorkBuddy私有化部署但管理控制台无法加载、API调用返回404或OAuth回调失败，则很可能是由于域名解析配置缺失或记录类型使用错误。WorkBuddy各服务模块对DNS解析类型有明确区分要求：控制台与API网关必须通过A记录直连服务器IP，而WAF防护、CDN加速及高防回源场景则强制使用CNAME。以下是具体配置规范与操作步骤：
一、控制台与API网关必须配置A记录
A记录将域名直接映射至私有化服务器的公网IPv4地址，是WorkBuddy核心服务唯一允许的解析方式。若误配为CNAME，将导致TLS证书校验失败、Host头丢失及网关路由中断，所有HTTPS请求均被拒绝。
1、登录您的DNS服务商控制台（如阿里云云解析DNS、腾讯云DNSPod或自建BIND）。
2、添加一条A记录，主机名填写workbuddy（对应完整域名为workbuddy.yourcompany.com），记录值填入私有化服务器的公网IPv4地址（如203.208.100.50）。
3、为API网关单独添加第二条A记录，主机名填写api（对应完整域名为api.workbuddy.yourcompany.com），记录值与上一条相同，确保同IP共用。
4、TTL值建议设为300秒（5分钟），便于后续快速切换；立即保存并等待DNS全网生效（通常需1–30分钟）。
二、WAF与高防场景必须使用CNAME记录
当WorkBuddy接入Web应用防火墙（WAF）或DDoS高防IP时，原始服务器IP必须隐藏，所有流量须经安全网关转发。此时必须将域名解析类型从A记录改为CNAME，并指向WAF厂商分配的专属CNAME地址，否则源站暴露且防护失效。
1、在WAF控制台（如腾讯云WAF、阿里云WAF或Cloudflare）中获取分配的CNAME地址（如wb-123456789.waf.tencentcdn.net）。
2、删除已存在的workbuddy.yourcompany.com的A记录。
3、新增一条CNAME记录，主机名仍为workbuddy，记录值粘贴上述CNAME地址，不可修改或截断。
4、同步为api.workbuddy.yourcompany.com添加相同CNAME记录，确保API网关流量也经WAF统一过滤。
5、在WAF后端配置中，将“回源地址”设为私有化服务器内网IP（如172.16.200.10），并启用隐藏源站真实IP选项。
三、OAuth回调与Webhook接收域名支持CNAME或A记录
oauth.workbuddy.yourcompany.com与hook.yourcompany.com两类域名不参与TLS终止和Host路由判断，仅用于HTTP重定向跳转与事件推送接收，因此同时兼容A记录与CNAME，但二者不可混用同一子域。
WorkBuddy 桌宠工厂 —— 给一张角色图、一个 codex.pet 链接、一条 codex-pets.net 下载 URL、或一份现成的精灵表，就能自动创建一只可联动 WorkBuddy 状态的桌面宠物。当用户说"创建桌宠"、"做一只桌宠"、"用这张图做桌宠"、"从 codex.pet 安装桌宠"、"导入 codex 桌宠 XX"、"装一下 codex-pets.net 上的 XX&quo
1、若企业已部署统一身份中台，可将oauth子域CNAME至SSO平台提供的CNAME地址（如sso-prod.corp-idp.com）。
2、若采用自建OAuth服务，必须配置A记录，记录值为OAuth服务所在服务器的公网IP。
3、webhook子域推荐使用A记录直连，避免CNAME引入额外DNS查询延迟；若需通过API网关统一调度，可CNAME至网关CNAME地址，但须确保网关已开启X-Forwarded-For透传与原始Host头保留功能。
四、静态资源域名必须使用CNAME接入CDN
static.workbuddy.yourcompany.com专用于分发前端JS/CSS/模型文件，必须通过CDN节点就近缓存与传输，禁止直连源站。使用A记录将导致全球用户访问延迟激增、并发承载能力归零，且违反WorkBuddy默认CSP策略。
1、在CDN服务商（如腾讯云CDN、Cloudflare或Akamai）中创建加速域名，源站填写私有化服务器内网IP及端口（如172.16.200.10:8080）。
2、获取CDN分配的CNAME地址（如static-abc123.cdn.qcloud.com）。
3、删除static子域原有A记录，新建CNAME记录，主机名static，记录值为上述CDN CNAME地址。
4、在CDN控制台配置HTTPS证书（必须为workbuddy.yourcompany.com通配符证书），并启用强制HTTPS跳转与Brotli压缩。
五、验证解析结果是否符合要求
DNS记录配置完成后，必须逐项验证类型、TTL与响应内容是否与WorkBuddy运行时预期一致，任何偏差都将触发服务降级或拦截。验证须在客户端本地与服务器端双侧执行。
1、在Windows/macOS/Linux终端执行：nslookup -type=A workbuddy.yourcompany.com 8.8.8.8，确认返回IPv4地址且无CNAME链路。
2、执行：nslookup -type=CNAME api.workbuddy.yourcompany.com 1.1.1.1，若配置WAF则应返回CNAME地址，否则报NXDOMAIN。
3、使用curl -vI https://workbuddy.yourcompany.com，检查响应头中Server字段是否为Nginx/Traefik，且Strict-Transport-Security头存在。
4、在私有化服务器内部执行dig @127.0.0.1 static.workbuddy.yourcompany.com，确认返回CDN节点IP而非源站IP。
