安全防护与敏感信息隔离说明
本页基于当前版本已落地实现与默认自建部署形态编制，适用于前端、API、知识库文件、向量索引与业务数据库部署在客户自有环境的场景。说明重点覆盖网络层安全、主机层安全、应用层安全、数据层安全、身份权限层安全，以及客户重点关注的私有知识库、邮箱授权码与核心经营信息隔离机制。
部署边界
当前系统采用自建/本地部署形态，前端、API、知识库文件、向量索引与业务数据库均可落在客户自有网络和主机边界内。
默认隔离单元
系统以租户为核心隔离单元，知识库、邮箱配置、处理记录、用量、支付记录等核心对象均以 tenant_id 进行归属控制。
披露口径
以下说明仅覆盖当前版本已落地能力与明确的部署前提，不将 WAF、堡垒机、KMS、EDR 等外部设施视为系统内建能力。
网络层安全
当前版本的网络层控制重点在于收敛访问来源、约束跨域边界，并在 HTTPS 生产环境下自动启用更严格的 Cookie 传输策略。
访问边界可收敛到自有网络
前端与 API 采用自建部署方式，可运行在客户本地网络、内网或受控反向代理之后，避免将核心业务流量默认暴露给第三方 SaaS 平台。
跨域访问受白名单控制
后端仅在配置了 api_cors_origins 时启用 CORS，并按白名单放行来源域名、方法与头部，避免任意站点直接跨域调用业务接口。
会话 Cookie 随 HTTPS 自动收紧
系统会根据 https、x-forwarded-proto 或 cf-visitor 判定是否启用 Secure Cookie；SameSite 会按同站/跨站场景自适应为 lax 或 none，以兼顾安全与代理兼容性。
主机层安全
主机层的防护边界由客户自有服务器承担，系统当前已落地的能力主要体现在本地落盘、自控目录与路径安全约束。
文件与向量索引默认本地落盘
租户文件、私有知识库文档、公共知识库文档与向量索引均写入本地 tenant_storage_root，不依赖外部托管式文件存储作为默认持久层。
目录访问带路径安全校验
知识库目录解析使用 safe_id 与 safe_join，对 kb_id 的格式、目录跳转与路径穿越做校验，防止通过 ../ 或非法路径直接越界访问主机文件。
公共区与租户区物理分区
公共知识库位于 public/knowledge_bases，租户私有知识库位于 tenant_{id}/knowledge_bases，主机文件层面即完成公共区与租户区的物理分离。
应用层安全
应用层主要通过接口校验、限频、幂等、功能边界约束以及公私数据面分离来降低滥用与误访问风险。
接口输入具备结构化校验
邮箱配置、知识库 ID、支付参数、管理指令等核心输入均通过 Pydantic 字段约束与服务端校验处理，减少非法值、超长值或错误结构直接进入业务链路。
验证码链路具备限频与时效控制
邮箱验证码默认具备有效期、最小发送间隔与每小时发送次数上限，降低暴力请求、撞库式重放与短信/邮件轰炸类滥用风险。
公有 Demo 与私有业务链路隔离
产品页 Demo 明确只调用公共知识库，不读取用户私有知识库；正式租户查询与草稿生成则在认证上下文内走租户私有链路，避免演示面误触客户私有数据。
支付与状态更新具备幂等约束
订单创建与支付状态更新使用幂等键、唯一约束和状态校验，减少重复提交、重复记账和并发重入带来的业务风险。
数据层安全
数据层控制重点在于租户归属、敏感值最小化落库、关键凭证摘要化保存，以及对业务留痕对象建立可审计记录。
核心业务表按 tenant_id 归属
用户、知识库、邮箱、消息线程、草稿、发送记录、用量、支付与退款等核心表均以 tenant_id 建立归属关系，并辅以唯一约束防止跨租户数据串写。
关键认证值不直接以明文主键存储
API Key 以带盐哈希值保存，邮箱 OTP 以 code_hash 保存；系统通过摘要校验完成认证，而不是回存或回显原始凭证。
支付侧仅保留必要运营字段
支付记录主要保存渠道参考号、订单状态、金额、对账字段等必要信息；银行卡渠道仅保留品牌与末四位用于运营对账，不在本系统内落库存储完整卡号或 CVV。
处理行为具备审计留痕基础
系统可记录查询用量、邮件草稿、发送记录、支付与退款状态等业务痕迹，为内部审计、问题回溯和运维排查提供依据。
身份权限层安全
身份与权限控制围绕“验证码登录、租户绑定、管理员分权、会话签名、过期用户门禁”这几条主线展开。
用户登录采用邮箱 OTP 校验
终端用户通过邮箱验证码登录；验证码验证通过后才会建立租户会话，未通过认证的请求无法访问租户控制台或租户 API。
会话由签名 Cookie 或 API Key 驱动
业务接口通过 X-API-Key 或签名后的 mm_mailrag_session 进行认证；服务端使用 session_secret 对会话签名校验，避免伪造简单明文会话。
管理员访问采用独立凭证边界
管理员控制台需单独提供 ADMIN_TOKEN 建立 mm_mailrag_admin 会话，与普通租户会话分离，避免把后台权限与普通业务登录混在同一认证面上。
订阅状态参与权限门禁
试用到期或订阅失效的账户会被前端门禁引导至付费页面，而不是继续访问完整控制台功能；私有知识库能力也受套餐与状态约束。
高敏感信息专项隔离说明
针对客户最关心的私有知识库数据、邮箱授权码与核心经营信息，当前系统采用“租户归属 + 存储分区 + 认证上下文 + 最小字段暴露”的组合控制策略。
私有知识库（Private KB）隔离说明
私有知识库在文件层、索引层和数据库层同时按租户隔离：目录位于 tenant_{id}/knowledge_bases/{kb_id}，知识库元数据与文档记录带 tenant_id，查询时必须在认证后的租户上下文中命中对应 kb_id。产品页 Demo 不会调用租户私有 KB，只走公共知识库链路。
邮箱授权码隔离说明
系统已支持“环境变量引用模式”：邮箱配置字段 password_env 在运行时会优先按环境变量名读取真实授权码，仅在未命中环境变量时才回退为字面值兼容模式。基于这一实现，生产环境建议将真实授权码保存在主机环境变量或密钥管理设施中，前端与数据库中仅保留引用名，而不要直接填写真实授权码。
核心经营信息隔离说明
租户名称、套餐状态、支付记录、邮件线程、草稿与发送记录、用量日志等经营敏感信息均按 tenant_id 归属，并通过用户会话或管理员边界访问。管理端仅展示运营所需的最小字段集，例如支付参考号、金额、状态、卡品牌与末四位，不向业务界面暴露完整支付敏感信息。
披露边界与部署前提
本页说明基于当前版本已落地实现。若客户需要更高等级的企业安全体系，例如 WAF、主机加固基线、操作审计堡垒机、磁盘透明加密、KMS/HSM、专用密钥轮换、集中式日志审计与告警平台等，应结合客户现有基础设施进行部署集成。换言之，本系统已经提供租户隔离、会话签名、OTP 校验、路径安全、摘要化认证值保存与审计留痕等应用内控制，但主机、网络出口与运维侧的高级防护仍应由正式生产环境配套落实。