子域名路由必须用app.Subdomain()或Party()显式创建分组,不可依赖Host头自动分流或路径前缀写法;否则子域请求因无匹配路由而404。

子域名路由必须用 app.Subdomain() 显式创建独立分组,不能靠 Host 头自动分流,也不支持路径式写法(如 /admin/xxx);否则所有子域请求都会 404。
子域名必须用 Subdomain() 或 Party() 显式注册
Iris 不会解析 Host 头并自动把请求派发到对应逻辑——你得亲手告诉它“这个分组只响应 admin.example.com”。漏掉这步,admin.example.com 的请求会进根路由,但根路由里没注册该路径,结果就是静默 404。
-
app.Subdomain("admin")→ 匹配admin.example.com(注意:不匹配www.admin.example.com) -
app.Subdomain("api").Subdomain("v1")→ 匹配v1.api.example.com(顺序重要:后调用的子域在 Host 左侧) -
app.Party("admin.")等价于app.Subdomain("admin"),只是语法糖,底层一样 - 泛子域用
app.Subdomain("{username}")或app.WildcardSubdomain(),但静态子域优先级更高
Subdomain 分组不继承根中间件和依赖注入
从 app.Subdomain("admin") 返回的 Party 是隔离实例,不是根 app 的子集。你在根上 Use() 的日志、鉴权中间件,不会自动生效;用 hero.Register() 注入的服务,也不会自动可用。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 必须手动挂载:
admin.Use(authMiddleware)、admin.Use(logger) - 数据库连接等依赖,需在子域分组里重新
admin.ConfigureContainer()或admin.Dependencies().Add(...) -
ctx.Values().Get("user_id")为空?大概率是中间件没在子域分组里复用,值根本没写进去 -
WildcardSubdomain()返回的分组更彻底:连UseGlobal()都不继承,必须全手动配
本地调试必须改 /etc/hosts,HTTPS 证书要单独传
浏览器不会凭空发出带子域的请求。不改 hosts,curl admin.localhost 就是 DNS 失败;不显式绑定 TLS,https://admin.example.com 会直接被拒绝。
- 本地加 hosts 条目:
127.0.0.1 admin.example.com、127.0.0.1 api.example.com - 子域分组必须自己调
.Listen()或.Run(),只启动根app.Run()不会代理子域 -
app.Subdomain("api").ListenTLS(":443", "cert.pem", "key.pem")—— 证书路径不能省,Iris 不复用主实例的 TLS 配置 - 若多个子域用不同证书(如通配符 vs 单独域名),需启动多个
iris.Application实例,Iris 不支持单实例 SNI
跨子域共享 Session 要设 CookieDomain 和 Redis 共享配置
子域间 ctx.GetCookie("session_id") 返回空,90% 是因为 Cookie 写入时没设对 Domain,浏览器压根不发送。
-
CookieDomain: ".example.com"(开头必须带点),否则admin.example.com和api.example.com无法共享 -
CookiePath: "/"、CookieSecure: true(生产)、CookieHTTPOnly: true也得显式配 - Redis 存储必须统一
Database和Prefix,否则多副本部署后用户频繁登出 - 前端跳转(如从
app.example.com点链接到api.example.com)失败?检查CookieSameSite,Lax 模式下可能被拦截,可临时设为SameSiteNoneMode+Secure
真正容易被忽略的是:子域分组的生命周期完全独立,包括中间件执行链、依赖容器、错误处理、静态文件托管位置——你以为配一次就全局生效,其实每一分组都得重来一遍。


















