codex-console安全基线教程API与WebSocket统一鉴权与默认口令强制改密完整指南【免费下载链接】codex-consolecodex-console 是一个集成化控制台项目支持任务管理、批量处理、数据导出、自动上传、日志查看与打包支持。项目地址: https://gitcode.com/gh_mirrors/co/codex-console 本文带你快速掌握codex-console的安全基线设计这个集成化控制台任务管理、批量处理、数据导出、自动上传、日志查看如何为API 与 WebSocket 提供统一鉴权以及默认口令强制改密流程如何防止未授权访问。新手按文中步骤走一遍即可把部署后的控制台调到安全可用状态。为什么控制台需要安全基线codex-console 的 Web UI 默认监听0.0.0.0:8000见 src/config/settings.py 中的webui_host/webui_port配置。端口一旦对局域网甚至公网开放以下风险就会真实存在默认访问密码admin123人人皆知等同于不设防默认密钥your-secret-key-change-in-production会被用于生成登录 Cookie 令牌泄露后登录态可被伪造WebSocket 频道任务日志、批量状态推送如果绕过鉴权日志内容就能被未登录者偷听。项目的应对思路很直接一个鉴权模块管住所有入口一套默认配置检测管住出厂裸奔状态。统一鉴权核心一个模块守住 API 与 WebSocket所有鉴权逻辑集中在 src/web/auth.py 一个文件里这也是你排查为什么 401/423/4403时唯一需要看的地方。登录令牌HMAC-SHA256 派生而非明文 Cookie登录成功后服务端不会把密码本身写进 Cookie而是用访问密码 密钥通过 HMAC-SHA256 派生出一段不可逆的令牌build_auth_tokenCookie 值 HMAC-SHA256(secret_key, access_password)校验时用secrets.compare_digest做恒定时间比较is_request_authenticated避免时序侧信道攻击。API 鉴权路由级依赖项一处生效、全局覆盖在 src/web/app.py 中整个/api前缀的路由器挂载了统一依赖app.include_router(api_router, prefix/api, dependencies[Depends(require_api_auth)])也就是说 src/web/routes/ 下的 accounts、tasks、registration、settings 等全部 REST 接口共享同一道闸门。require_api_authsrc/web/auth.py#L72-L83的行为分两档场景响应含义仍在默认口令/默认密钥423password_change_required先访问/setup-password改密未登录或 Cookie 失效401 未登录或登录已失效重新走登录页对应的回归测试见 tests/test_security_and_task_routes.py它直接断言/api/accounts路由必须挂载require_api_auth依赖项——防止后续开发时悄悄拆掉鉴权。WebSocket 鉴权同样的令牌自定义关闭码WebSocket 无法使用 HTTP 状态码项目用关闭码表达同样的语义websocket_auth_failure4401 unauthorized令牌不匹配连接在accept之前被直接拒绝4403 password_change_required默认口令未改任何实时频道都不开放。两条实时频道 task_websocket任务日志与 batch_websocket批量状态都在建立连接的第一时间调用 is_websocket_authenticated 校验 Cookie校验不过就不accept未授权者拿不到任何一条历史日志。默认口令强制改密流程302 重定向的安全闸门触发条件什么时候会强制改密is_default_security_config_active 定义了出厂裸奔状态满足任意一条即命中访问密码为空访问密码仍为admin123密钥为空密钥仍为默认占位值。服务启动时若命中该状态日志会明确提示Default security config detected, visit /setup-passwordsrc/web/app.py#L116-L117。改密流程逐步拆解 完整流程对应 templates/setup_password.html 页面与 /setup-password 接口强制跳转默认口令状态下访问任意页面/、/accounts、/settings等都会被_guard_page_request以302重定向到/setup-password验证旧密码表单需填写当前密码错误则返回Current password is incorrect强度校验新密码至少 8 位、两次输入必须一致、禁止仍使用admin123一键换血校验通过后除了写入新密码还会用secrets.token_urlsafe(48)随机重生成整个密钥src/web/app.py#L299-L302旧令牌全部作废同时删除旧 Cookie 并跳转登录页。 关键点改密不只是换个口令密钥的同步重生成让所有已派生的登录令牌一次性失效天然完成一次全员重登录。登录、Cookie 与登出闭环细节登录/login 用secrets.compare_digest校验密码成功后签发 Cookiewebui_auth并设置HttpOnlySameSiteLax前端 JS 无法读取抵御 XSS 窃取 Cookie登出/logout 仅删除 Cookie——由于令牌是密码密钥的纯函数派生删掉 Cookie 即彻底失效无需维护服务端会话表调试文档收口/api/docs、/api/redoc仅在debugTrue时开启src/web/app.py#L158-L159生产环境建议保持关闭。敏感配置清单密钥类字段全部走 SecretStr改完口令后建议顺手检查数据库中其他出厂即敏感的字段。在 src/config/settings.py 中所有标记is_secretTrue的配置项都会以 Pydantic 的SecretStr类型加载打印日志时自动打码为***webui_access_password/webui_secret_key登录与令牌核心security.encryption_key数据库敏感数据加密密钥默认值同样是占位符生产环境必须更换proxy_password、yyds_mail.api_key、tm.api_key、cpa.api_token等第三方凭据。项目内置的动态代理凭据即属此类proxy_dynamic_api_key。项目文档中代理资源的示例横幅如下实际部署时请替换为你自己的代理与密钥新手自检清单 ✅部署 codex-console 后用这 6 条逐项过一遍浏览器访问任意页面是否被重定向到/setup-password改密完成后不再出现用旧密码重新登录应提示密码错误旧令牌已作废未登录直接请求/api/accounts应返回401而非数据用wscat等工具直连ws://host:8000/api/ws/task/xxx不带 Cookie连接应被以4401关闭检查debug配置为false确认/api/docs不可访问数据库中的security.encryption_key已替换为自定义值。小结codex-console 的安全基线可以概括为三句话src/web/auth.py一个模块统一鉴权 API 与 WebSocketHMAC 派生令牌 恒定时间比较 HttpOnly Cookie保证登录态不可伪造、不可窃取默认口令强制改密 密钥自动重生成保证服务一上线就不裸奔。按本文清单走完一遍你的控制台就具备了可对外共享的最小安全配置。【免费下载链接】codex-consolecodex-console 是一个集成化控制台项目支持任务管理、批量处理、数据导出、自动上传、日志查看与打包支持。项目地址: https://gitcode.com/gh_mirrors/co/codex-console创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考