diff --git a/.eslintrc-auto-import.js b/.eslintrc-auto-import.js index bbc9a1a..1d240d8 100644 --- a/.eslintrc-auto-import.js +++ b/.eslintrc-auto-import.js @@ -15,7 +15,6 @@ export default { "invalidateAll": true, "navigating": true, "onDestroy": true, - "onMount": true, "page": true, "preloadCode": true, "preloadData": true, diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b8327cb..2761518 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,16 +56,16 @@ jobs: - name: 前端依赖漏洞扫描 run: pnpm run audit:deps - - name: 依赖方向基线(12 service + 1 middleware + 0 router) + - name: 依赖方向基线(middleware 与 router 不得 import repository) working-directory: server run: | - HITS=$(git grep -ln "MyBlog/internal/repository" -- internal/service internal/middleware internal/router \ + HITS=$(git grep -ln "MyBlog/internal/repository" -- internal/middleware internal/router \ | grep -v '_test\.go$' || true) COUNT=$(printf '%s' "$HITS" | grep -c . || true) - echo "依赖基线命中文件数: ${COUNT}" - echo "依赖基线命中文件清单:" + echo "违例边命中文件数: ${COUNT}" + echo "违例边命中文件清单:" printf '%s\n' "$HITS" - test "$COUNT" -le 13 + test "$COUNT" -eq 0 - name: 公共包单测与类型检查 run: pnpm run test:packages diff --git a/AGENTS.md b/AGENTS.md index da2a6ca..4321034 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,17 +9,18 @@ 违反必须返工,每条附验证方式。 1. **依赖只准向下**。后端 `handler → service → repository → domain`,禁止 service import handler、repository import service/handler、handler/middleware/router 直接 import repository;前端 `apps → @myblog/api → @myblog/http → @myblog/shared`,禁止 packages 反向 import apps,禁止页面/组件直接 import `ky`(唯一豁免:各应用 `src/lib/service/index.ts` 的令牌刷新直连)。 - 验证:在 `server/` 下执行 `git grep -ln "MyBlog/internal/repository" -- internal/service internal/middleware internal/router ':(exclude)*_test.go'`,基线 13 个文件(service 12 + middleware 仅 `identity.go` + router 0),只减不增。 + 验证:在 `server/` 下执行 `git grep -ln "MyBlog/internal/repository" -- internal/middleware internal/router ':(exclude)*_test.go'`,应为空;`service → repository` 属允许边,不在此命令统计,完整口径见 `docs/debt/architecture.md` 第 1 条。 2. **类型唯一真相源**。后端 `internal/domain` 与 `internal/model` 的 json tag 即 API 契约;前端接口类型唯一来源为 `@myblog/api/modules/*/types`,apps 内禁止定义与后端请求/响应同构的 interface/type;通用响应信封唯一来源为 `@myblog/shared` 的 `ApiResponse`(底层为 `BaseApiResponse`)。 验证:`git grep -n "interface BaseApiResponse" -- apps` 应为空。 3. **契约先行,双端对齐**。改 wire 格式(请求/响应结构、错误码语义、认证协议)必须同一变更窗口内同步两端,禁止"先改后端、前端以后再说";改认证协议先更新 `contracts/auth-protocol.md`,改类型镜像跑 `pnpm run contract:check`。新增业务模块必须同时落地后端四层、`packages/api/src/modules//` 与两应用 `lib/api/index.ts` 注册。 4. **单一权威,禁止私自实例化**。业务规则(状态流转、slug 生成、密码强度、权限判定)权威在后端,前端只做展示层优化;RBAC 权限表权威为生产 `server/configs/config.yaml` 的 `rbac` 节,权限经登录响应 `permissions[]` 下发,`apps/admin/src/lib/constants/auth.ts` 的映射仅作未下发时的降级;依赖一律构造函数注入,生产实例化点仅组合根 `server/cmd/myblog/`(`main.go` 管生命周期、`deps.go` 按域装配),禁止在 service/router/middleware 内 `NewXxxService()`。 验证:`git grep -n "NewRBACService()" -- server` 的生产命中应仅 `cmd/myblog/deps.go` 一处。 -5. **禁止复制粘贴式共享**。两 app 间禁止新增逐字或近似重复文件,公共逻辑下沉 packages;存量逐字重复仅 `src/lib/stores/auth.ts`(15 行 ×2)与 `src/lib/components/theme-toggle.svelte`(45 行 ×2),改任一份必须同步另一份。 - 验证:`git diff --no-index` 上述两份文件应零差异。 +5. **禁止复制粘贴式共享**。两 app 间禁止新增逐字或近似重复文件,公共逻辑下沉 packages,跨应用共用的组合组件下沉 `packages/components`;唯一保留的逐字重复是 `src/lib/stores/auth.ts`(10 行 ×2),为包内无法解析 `$lib/api` 而保留的纯注入接缝,上限 10 行,改任一份必须同步另一份。 + 验证:`git diff --no-index apps/web/src/lib/stores/auth.ts apps/admin/src/lib/stores/auth.ts` 应零差异;`git ls-files "*theme-toggle.svelte"` 应仅 1 个,位于 `packages/components`。 6. **数据加载归位**。`apps/web` 新页面禁止 `onMount` 取数,用 `+page.server.ts` / `+page.ts` 的 load;`apps/admin` 新页面同样禁止 `onMount` 取数,含客户端读写操作的页面配 load + 页面状态模块(`.svelte.ts`),只读页由 load 直出 page data,load 内禁止调用认证接口;API 调用不得深入叶子组件。 -7. **部署形态为单实例**(有意取舍,非待修缺陷)。应用进程、MySQL、网关各一份,无副本与故障转移;会话令牌表与限流计数均为进程内存结构,服务重启或发布将导致全体用户登出,发布窗口需提前预告;故障即停站,无 RTO 承诺,RPO 为 24 小时。扩容前必须完成令牌表持久化、限流器外置、补 `SetTrustedProxies` 三项改造。 - 验证:`git grep -n "SetTrustedProxies" -- server` 与 `git grep -n "replicas" -- docker-compose.yml` 均应为空。 +7. **部署形态为单实例终态**(已接受,非待修缺陷)。应用进程、MySQL、网关各一份,全部部署于同一台服务器,由同一 nginx 实例按端口区分出入口,**确定不扩容**;会话令牌表与限流计数均为进程内存结构,服务重启或发布将导致全体用户登出,发布窗口需提前预告;故障即停站,无 RTO 承诺,RPO 为 24 小时。若未来改变该决定,扩容前必须先完成令牌表持久化与限流器外置两项改造。 + 验证:`git grep -n "replicas" -- docker-compose.yml` 应为空;`git grep -n "SetTrustedProxies" -- server` 应命中 `internal/router/router.go`。 + 代理信任链与本形态无关,受信来源唯一权威为 `security.trusted_proxies`,容器编排须经 `MYBLOG_SECURITY_TRUSTED_PROXIES` 注入容器网段,见 `docs/debt/security-runtime.md` 第 4 条。 8. **先确认产品定位**。单作者个人博客,不开放注册、无找回密码通道:账号由管理员创建(首次部署 `pnpm run seed:admin`,之后在后台用户管理页新增),忘记密码由超级管理员经 `POST /api/users/update` 重置;游客可浏览并提交评论(受审核设置约束),点赞/收藏/关注需登录。功能提案前先确认是否与之冲突;新增数据收集场景须先同步 `apps/web` 的 `/privacy` 页告知。 ## 2. 完成前自检 @@ -44,6 +45,7 @@ MyBlog/ │ ├── http/ # HTTP 请求器(ky 封装,认证回调注入) │ ├── api/ # 后端接口模块与响应类型(12 个模块工厂) │ ├── auth/ # 认证会话组装(createAuthStore 工厂,注入式) +│ ├── components/ # 跨应用组合组件(由 stock 组件组合,按包名导入,无应用别名) │ └── ui/ # shadcn-svelte 基础组件(stock,主题注入) ├── server/ # Go 后端(Gin + GORM + MySQL) ├── contracts/ # 认证与 i18n 协议、错误码口径、契约金样本 @@ -77,19 +79,19 @@ pnpm run go:quality / go:vulncheck / audit:deps - **分层**:`handler`(HTTP 与 DTO 映射)→ `service`(业务)→ `repository`(持久化),路由注册在 `internal/router/`;各层职责与边界见 `docs/development.md`「分层设计」与 `internal/{handler,service,repository,middleware}/README.md`。 - **错误分档**:service 错误唯一经 `internal/handler/error.go` 的 `HandleServiceError` 分档为 401/403/404/400,未分类错误脱敏为 500「服务器内部错误」且只把原文写日志;`binding` 校验失败由 handler 直接 `response.BadRequest` 返回 400;禁止模块内新增私有映射,新增哨兵须同步扩展映射集合与 `contracts/errors.yaml`。完整口径见 `internal/handler/README.md`。 - **统一响应**:统一经 `pkg/response`,业务结果一律 HTTP 200 并以 `code` 区分;信封结构、响应码常量与 404/503 例外见 `server/pkg/response/README.md`。 -- **类型归属**:领域实体在 `internal/domain`,GORM 实体在 `internal/model`,`repository` 不得新增实体或 DTO,对外响应禁止直出 GORM 实体(存量违例见 `docs/debt/security-runtime.md` 第 1 条);请求/响应 DTO 以所属业务域的 service 包内定义为常态(如 `service.CreateArticleRequest`),用户域的 `CreateUserRequest`/`UpdateUserRequest` 在 `internal/domain/dto.go`,短参数 DTO 可就地声明在 handler。 +- **类型归属**:领域实体在 `internal/domain`,GORM 实体在 `internal/model`,`repository` 不得新增实体或 DTO,对外响应禁止直出 GORM 实体;请求/响应 DTO 以所属业务域的 service 包内定义为常态(如 `service.CreateArticleRequest`),用户域的 `CreateUserRequest`/`UpdateUserRequest` 在 `internal/domain/dto.go`,短参数 DTO 可就地声明在 handler。 - **命名与接口位置**:Go 字段与 json tag 用小驼峰;接口与实现同包声明并统一 `XxxInterface` 后缀(存量 `UserService`、`RBACService`、`UserRepository` 未带后缀,触碰时统一);各层依赖接口而非实现,`router` 不得重复定义接口。 - **数据库**:表结构硬性约定(生命周期与状态字段、字段级 `comment`、唯一索引与普通索引、删除策略、时间精度、多段写库事务化)与迁移双轨(开发 `AutoMigrate`、生产 golang-migrate)见 `docs/database-architecture.md`,迁移入口为 `internal/database/migrate.go` 与 `pnpm run migrate`。 -- **认证与密码**:bcrypt 成本 `BcryptCost = 12`;令牌为服务端签发的不透明随机串,内存令牌表是身份唯一权威(单实例前提),刷新即旋转、登出撤销令牌对、改密撤销该用户全部令牌。线格式与撤销语义见 `contracts/auth-protocol.md`,实现要点见 `internal/service/README.md`。 +- **认证与密码**:bcrypt 成本 `BcryptCost = 12`;令牌为服务端签发的不透明随机串,内存令牌表是身份唯一权威(单实例终态前提),刷新即旋转、登出撤销令牌对、改密撤销该用户全部令牌。线格式与撤销语义见 `contracts/auth-protocol.md`,实现要点见 `internal/service/README.md`。 - **配置与中间件**:`internal/config` 经 Viper 读 `configs/config.yaml`(YAML 为唯一来源);中间件覆盖访问日志与 panic 恢复及 RequestID、CORS、安全、认证、RBAC、限流、语言协商与身份解析,认证/权限中间件只依赖 `IdentityProvider` 抽象。配置项与中间件清单以 `internal/config/README.md`、`internal/middleware/README.md` 为准。 - **入口与工具包**:服务入口 `cmd/myblog/`,种子入口 `cmd/seed/`(逻辑 `internal/database/seed.go`),通用包见 `server/pkg/`。 ## 6. 前端约定(apps/ + packages/) - **框架**:SvelteKit + Svelte 5 runes + TypeScript,不使用 Options API;`apps/web` 为前台 toC、SSR 路线(adapter-node),`apps/admin` 为后台 toB、SPA 路线(`ssr=false`、adapter-static,`paths.base='/admin'`)且无 i18n。 -- **组件库**:shadcn-svelte 基础组件统一在 `packages/ui` 并保持 stock,经 `$ui` 与 `$ui/*` 引入;组件归属、禁止在应用内重写与主题注入细则见 `docs/ui-design-system.md`。 +- **组件库**:shadcn-svelte 基础组件统一在 `packages/ui` 并保持 stock,经 `$ui` 与 `$ui/*` 引入;由 stock 组件组合、两应用共用的组件归属 `packages/components`,按包名 `@myblog/components/` 导入,禁止塞进 `packages/ui` 或两应用各写一份;组件归属、禁止在应用内重写与主题注入细则见 `docs/ui-design-system.md`。 - **别名**:各应用 `svelte.config.js` 声明 `$ui`、`$ui/*`、`@/*`(应用自身 `src`),前台另有 `$i18n` 与构建期 `#fonts` 别名,`$lib` 由 SvelteKit 隐式提供;对照见 `docs/development.md`「关键技术配置」。 -- **样式**:TailwindCSS v4(`@tailwindcss/vite`);`app.css` 只做聚合入口(含 `@source '../../../packages/ui/src'`),设计令牌在同应用 `src/styles/tokens.css`,`packages/ui` 不携带全局样式;前台为编辑杂志主题(含 `--signal` 与 `--color-line` 别名),后台为原始主题(无 `--signal`)。 +- **样式**:TailwindCSS v4(`@tailwindcss/vite`);`app.css` 只做聚合入口(含 `@source '../../../packages/ui/src'` 与 `@source '../../../packages/components/src'`),设计令牌在同应用 `src/styles/tokens.css`,`packages/ui` 不携带全局样式;前台为编辑杂志主题(含 `--signal` 与 `--color-line` 别名),后台为原始主题(无 `--signal`)。 - **API 层**:`packages/http` 提供 `createHttpClient` 工厂,`packages/api` 提供 12 个模块工厂,认证会话由 `@myblog/auth` 的 `createAuthStore` 组装;应用侧 `src/lib/service` 注入认证与提示回调、`src/lib/api` 实例化接口,一律 `POST` 调用后端。新增接口必须先加在 `packages/api`,禁止页面直连 ky。 - **状态**:认证 store 逻辑已下沉 `@myblog/auth`(两应用各持薄封装),新公共状态逻辑必须下沉 packages,禁止第三处复制。 - **i18n(仅前台)**:`@inlang/paraglide-js` + `project.inlang` / `messages/*.json5`(必须保持 JSON 兼容写法,否则编译失败);已接入文件禁止回退硬编码,新增用户可见文案优先经 `m['ui:...']()` 取词,已接入面与其余页面分批口径见 `docs/debt/frontend.md` 第 7 条。 @@ -102,13 +104,13 @@ pnpm run go:quality / go:vulncheck / audit:deps - **格式化覆盖范围**:lint-staged 只对 `apps/**/src/**` 的脚本与组件文件、任意目录下的 `*.{json,yaml,yml}` 运行 prettier,对 `server/**/*.go` 运行 gofmt 与 goimports;`packages/**` 的源码不在任何 format 门禁覆盖内,新增或改动 packages 文件须手动执行 `npx prettier --write `。 - **注释**:只解释代码无法直接表达的意图、业务规则、约束、原因、风险与副作用,不复述代码;完整写作要求遵循全局规范 `~/.dsh/AGENTS.md` 第 4 节。 - **测试文件位置**:前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录;跨用例共享的测试替身与夹具置于包内 `src/test/`,不放入 `__tests__/`。 -- **测试纪律**:后端各层与 `pkg/*` 均有 `*_test.go`,新增后端关键逻辑必须配套同目录测试;`packages/api`、`packages/auth`、`packages/http` 与两应用单测分别经 `pnpm run test:packages`、`pnpm run test:apps` 纳入门禁,新增 packages 公共逻辑与页面状态模块(`.svelte.ts`)须配套 `*.test.ts`,并为所在 package 补 `typecheck`、`test` 脚本且登记进根 `test:packages`。`pnpm run check` 与 `typecheck:web` 只做类型检查,不是单元测试。 +- **测试纪律**:后端各层与 `pkg/*` 均有 `*_test.go`,新增后端关键逻辑必须配套同目录测试;`packages/api`、`packages/auth`、`packages/components`、`packages/http` 与两应用单测分别经 `pnpm run test:packages`、`pnpm run test:apps` 纳入门禁,新增 packages 公共逻辑与页面状态模块(`.svelte.ts`)须配套 `*.test.ts`,并为所在 package 补 `typecheck`、`test` 脚本且登记进根 `test:packages`。`pnpm run check` 与 `typecheck:web` 只做类型检查,不是单元测试。 - **提交**:提交信息用简体中文、符合 commitlint 的 conventional commits(type 枚举见 `commitlint.config.js`);单次提交跨度过大时补充正文说明。 ## 8. 文档地图 - `docs/architecture-rules.md`:第 1 节红线的完整裁决细则、债务索引与验证命令、历史教训与重构分期(与本文冲突时以该文件为准)。 -- `docs/debt/`:债务条目分册(结构类型 / 前端复用 / 安全运行时 / 测试),基线只减不增。 +- `docs/debt/`:债务与取舍登记分册(结构类型 / 前端复用 / 安全运行时),债务条目基线只减不增,已接受取舍只守其上限与前提。 - `docs/development.md`:环境设置、开发工作流、分层与模块设计、工具陷阱、代码风格示例。 - `docs/database-architecture.md` 与 `docs/database/schema.sql`:数据库设计说明与参考 DDL(实际结构以 GORM 模型为准,生产经 `server/migrations/` 增量迁移)。 - `docs/ui-design-system.md`:视觉、动效与可访问性准则。 diff --git a/README.md b/README.md index d413c84..b7f52a6 100644 --- a/README.md +++ b/README.md @@ -263,5 +263,6 @@ Domain Layer → 领域实体与请求/响应 DTO(全系统唯一类型语 - [x] 前台界面多语言(Header、Footer、通知铃铛、友链弹窗、错误页与 demo 页已接入 paraglide,其余页面待分批接入) - [x] 契约金样本与类型锚定门禁、CI 质量流水线与依赖漏洞扫描 - [x] 部署配置和 Docker 支持(MySQL + 后端 + 前台 + Nginx + 备份单实例编排) -- [ ] 前端窄屏与响应式细节打磨(后台字典页工具栏窄屏遗留未完成,见 `docs/debt/frontend.md` 第 8 条) -- [ ] 扩容前置改造三项(令牌表持久化、限流器外置、补 `SetTrustedProxies`,见 `docs/architecture-rules.md` 第 7 节) +- [ ] 前端窄屏与响应式细节打磨(后台字典页工具栏窄屏遗留已按 `docs/debt/frontend.md` 第 8 条修复,其余页面按需跟进) +- [x] 部署形态定型为单实例终态(确定不扩容;令牌表持久化与限流器外置降为变更前提,见 `docs/architecture-rules.md` §7.2) +- [x] 代理信任链收敛(受信来源由 `security.trusted_proxies` 白名单决定,容器编排经环境变量注入网段,伪造转发头不再生效,见 `docs/debt/security-runtime.md` 第 4 条) diff --git a/apps/admin/package.json b/apps/admin/package.json index 03cf846..01afa2a 100644 --- a/apps/admin/package.json +++ b/apps/admin/package.json @@ -29,6 +29,7 @@ "@milkdown/kit": "7.22.1", "@myblog/api": "workspace:*", "@myblog/auth": "workspace:*", + "@myblog/components": "workspace:*", "@myblog/http": "workspace:*", "@myblog/shared": "workspace:*", "@myblog/ui": "workspace:*", diff --git a/apps/admin/src/app.css b/apps/admin/src/app.css index e795294..7a5469b 100644 --- a/apps/admin/src/app.css +++ b/apps/admin/src/app.css @@ -9,8 +9,9 @@ @import './styles/animations.css'; @import './styles/milkdown.css'; -/* 纳入 packages/ui 源码,Tailwind v4 默认不扫描 node_modules 与仓库外目录。 */ +/* 纳入 packages/ui 与 packages/components 源码,Tailwind v4 默认不扫描 node_modules 与仓库外目录。 */ /* packages/ui 源码变更后工具类未更新时,重启 dev server 可强制重新扫描。 */ @source '../../../packages/ui/src'; +@source '../../../packages/components/src'; @custom-variant dark (&:is(.dark *)); diff --git a/apps/admin/src/lib/components/admin/page-header.svelte b/apps/admin/src/lib/components/admin/page-header.svelte index 10ec689..fe3f565 100644 --- a/apps/admin/src/lib/components/admin/page-header.svelte +++ b/apps/admin/src/lib/components/admin/page-header.svelte @@ -1,6 +1,6 @@ - - diff --git a/apps/admin/src/lib/stores/auth.ts b/apps/admin/src/lib/stores/auth.ts index fdfca3a..1008968 100644 --- a/apps/admin/src/lib/stores/auth.ts +++ b/apps/admin/src/lib/stores/auth.ts @@ -1,15 +1,10 @@ import { createAuthStore } from '@myblog/auth' -import { browser } from '$app/environment' -// 认证 store 实例:注入环境判定与登出接口,核心逻辑统一下沉至 @myblog/auth。 +// 登出经动态导入调用,避免认证 store 与服务层形成循环依赖; +// 会话令牌经 Cookie 携带,登出由服务端撤销令牌并清除 Cookie。 export const authStore = createAuthStore({ - isBrowser: () => browser, logoutApi: async () => { - // 动态导入避免与服务层形成循环依赖。 - // 会话令牌经 Cookie 携带,登出由服务端撤销令牌并清除 Cookie。 const { UserAPI } = await import('$lib/api') await UserAPI.logout() } }) - -export type { AuthState } from '@myblog/auth' diff --git a/apps/admin/src/routes/(auth)/login/+page.svelte b/apps/admin/src/routes/(auth)/login/+page.svelte index e8e21cd..2810bd5 100644 --- a/apps/admin/src/routes/(auth)/login/+page.svelte +++ b/apps/admin/src/routes/(auth)/login/+page.svelte @@ -1,9 +1,9 @@ - - diff --git a/apps/web/src/lib/stores/auth.ts b/apps/web/src/lib/stores/auth.ts index fdfca3a..1008968 100644 --- a/apps/web/src/lib/stores/auth.ts +++ b/apps/web/src/lib/stores/auth.ts @@ -1,15 +1,10 @@ import { createAuthStore } from '@myblog/auth' -import { browser } from '$app/environment' -// 认证 store 实例:注入环境判定与登出接口,核心逻辑统一下沉至 @myblog/auth。 +// 登出经动态导入调用,避免认证 store 与服务层形成循环依赖; +// 会话令牌经 Cookie 携带,登出由服务端撤销令牌并清除 Cookie。 export const authStore = createAuthStore({ - isBrowser: () => browser, logoutApi: async () => { - // 动态导入避免与服务层形成循环依赖。 - // 会话令牌经 Cookie 携带,登出由服务端撤销令牌并清除 Cookie。 const { UserAPI } = await import('$lib/api') await UserAPI.logout() } }) - -export type { AuthState } from '@myblog/auth' diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index ae7e65e..2bfafc1 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -77,8 +77,8 @@ export default ({ mode }: ConfigEnv) => { } }, ssr: { - // ui 包以源码直连方式被引用,需参与 SSR 编译以支持 .svelte 组件。 - noExternal: ['@myblog/ui'] + // ui 与 components 包均以源码直连方式被引用,需参与 SSR 编译以支持 .svelte 组件。 + noExternal: ['@myblog/ui', '@myblog/components'] }, resolve: { alias: { diff --git a/contracts/auth-protocol.md b/contracts/auth-protocol.md index 51aea6b..1322e53 100644 --- a/contracts/auth-protocol.md +++ b/contracts/auth-protocol.md @@ -26,7 +26,7 @@ - 令牌自身不承载用户标识与有效期,身份与生命周期登记在服务端令牌表;`ValidateAccessToken` 与 `ValidateRefreshToken` 以查表结果为唯一依据。 - 校验同时核对令牌类型,访问令牌与刷新令牌不可互换使用。 - 令牌不可由调用方构造:任何未经服务端签发的串都会因查表失败被拒绝,不存在依据请求内容现算凭证的路径。 -- 服务重启会清空令牌表,多实例部署前必须将令牌表迁至共享存储(单实例约束与扩容前置改造见 `docs/architecture-rules.md` §7)。 +- 服务重启会清空令牌表;本项目为单实例终态、确定不扩容,故令牌表不迁移;若未来改变该决定,扩容前必须迁至共享存储(见 `docs/architecture-rules.md` §7.2)。 ## 3. 刷新协议与 Cookie 会话 @@ -79,13 +79,13 @@ - Header 通道:请求头 `Authorization: Bearer `,请求体可选提交 `{ "refreshToken": "" }`,提交后访问与刷新令牌一并撤销。 - Cookie 通道:会话 Cookie 存在时访问与刷新令牌一并撤销,响应以 `Max-Age=-1` 指示浏览器清除两个会话 Cookie。 - 修改密码成功后服务端撤销该用户当前全部既有令牌,客户端须清除本地状态并引导重新登录。 -- 撤销即从服务端令牌表移除记录,过期记录随签发惰性清理(内存实现,仅单实例生效)。 +- 撤销即从服务端令牌表移除记录,过期记录随签发惰性清理(内存实现,在单实例终态下即为唯一权威)。 ## 7. 已知限制(登记) | 限制 | 影响 | 计划 | |---|---|---| -| 令牌表为内存 map(已加互斥锁,过期记录随签发惰性清理) | 服务重启或发布导致全体用户登出;多实例部署即失效 | 单实例前提与扩容前置改造见 `docs/architecture-rules.md` §7 | +| 令牌表为内存 map(已加互斥锁,过期记录随签发惰性清理) | 服务重启或发布导致全体用户登出;多实例部署即失效 | 单实例为终态故不迁移;变更前提见 `docs/architecture-rules.md` §7.2 | | 登录失败(密码错误)同样返回 code 401 | 前端已排除登录端点与 `/auth/session` 自身,二者均不触发自动续期 | 已在 `packages/http/src/client.ts` 固化 | | 跨标签页对齐依赖 `storage` 事件送达时机 | 事件送达前本页仍展示已失效的登录态,直到首个请求返回 code 401 被纠正 | 登录态无本地令牌可误用,服务端会话 Cookie 为唯一裁决方 | | 并发 401 各自发起续期 | 续期即旋转,后到的请求会携带已被撤销的旧 Cookie 而失败 | 续期经 `refreshSingleFlight` 单飞,并发请求共享同一次续期 | diff --git a/deploy/README.md b/deploy/README.md index 0201eb3..c3e1852 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -20,7 +20,8 @@ - 编排中无副本声明与故障转移(`git grep -n "replicas" -- docker-compose.yml` 应为空),应用进程、MySQL、网关各一份,**不支持按多副本假设做设计与承诺**。 - 会话令牌表与请求限流计数均为进程内存结构,`server` 容器重启或重新部署将导致**全体用户登出**,发布窗口需提前预告;任一组件故障即停站,恢复依赖人工介入,无 RTO 承诺,RPO 为 24 小时(`docs/operations/backup-restore.md`)。 -- 扩容前置改造三项见 `docs/architecture-rules.md` §7.2。 +- 单实例为**终态**,本项目确定不扩容;若未来改变该决定,扩容前须先完成令牌表持久化与限流器外置两项改造(见 `docs/architecture-rules.md` §7.2)。 +- 代理信任链已收敛:仅 `MYBLOG_SECURITY_TRUSTED_PROXIES` 列出的来源所携带的 `X-Forwarded-For` 参与客户端 IP 解析,编排默认注入 `172.16.0.0/12`;自定义 Docker 地址池时须同步修改,漏改会让客户端 IP 退化为 nginx 容器地址,见 `docs/debt/security-runtime.md` 第 4 条。 ### 健康探针 @@ -45,8 +46,8 @@ `server` 容器的其余参数经 `MYBLOG_*` 前缀环境变量注入:`MYBLOG_SERVER_MODE=release`、 `MYBLOG_SERVER_HOST=0.0.0.0`、`MYBLOG_DATABASE_HOST=mysql`、`MYBLOG_DATABASE_PORT=3306`、 -`MYBLOG_DATABASE_USERNAME=root`。变量名由 `MYBLOG_` 加配置键的大写下划线形式构成, -列表与映射类配置无法经环境变量表达,见 `server/internal/config/config.go`。 +`MYBLOG_DATABASE_USERNAME=root`、`MYBLOG_SECURITY_TRUSTED_PROXIES=172.16.0.0/12`。变量名由 `MYBLOG_` 加配置键的大写下划线形式构成, +列表与映射类配置无法经环境变量表达(代理信任链按逗号分隔的专用通道除外),见 `server/internal/config/config.go`。 ### 数据卷 diff --git a/docker-compose.yml b/docker-compose.yml index 8956a3f..f0fa4c4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -50,6 +50,9 @@ services: # 指标监听绑定容器网卡,仅同 compose 网络的抓取端可访问,不发布到宿主机端口。 MYBLOG_METRICS_ENABLED: 'true' MYBLOG_METRICS_ADDR: 0.0.0.0:9090 + # 代理信任链:nginx 是唯一入口且 server 未发布端口,仅容器网络可达后端, + # 故信任 Docker 私有网段;自定义地址池时须同步改为实际网段,多项以逗号分隔。 + MYBLOG_SECURITY_TRUSTED_PROXIES: 172.16.0.0/12 volumes: - uploads:/app/uploads diff --git a/docs/architecture-rules.md b/docs/architecture-rules.md index 8ecffa7..99cbd87 100644 --- a/docs/architecture-rules.md +++ b/docs/architecture-rules.md @@ -6,7 +6,7 @@ > > **效力**:本手册效力高于普通文档;与更具体的细则冲突时以更具体者为准。 > -> **分册**:第 1 至 7 节为规则本体,第 8 节为债务索引,第 9 至 10 节为历史登记;债务的完整条目(状态、基线数值、验证命令、完整红线)按关注域分册在 [`debt/`](./debt/README.md)。 +> **分册**:第 1 至 7 节为规则本体,第 8 节为债务与取舍索引,第 9 至 10 节为历史登记;条目完整内容(状态、基线或上限、验证命令、红线)按关注域分册在 [`debt/`](./debt/README.md)。 --- @@ -18,7 +18,7 @@ | 【约定】 | 命名、格式、注释等风格约束 | 应当修正 | | 【债务】 | 已存在的违例,登记基线与验证命令 | **基线只减不增**(条目分册见 [`debt/`](./debt/README.md)) | -**基线只减不增是本手册的核心执行机制**:存量违规不要求立即修复,但任何改动使债务指标恶化,即新增违例文件、新增实例化点或新增重复代码时判定违规。每条债务附带验证命令,任务完成前 Agent 必须自检。 +**基线只减不增是本手册的核心执行机制**:登记为债务的违例不要求立即修复,但任何改动使债务指标恶化,即新增违例文件、新增实例化点或新增重复代码时判定违规。已接受取舍不设基线,改守其在登记条目中写明的上限与前提。每条债务附带验证命令,任务完成前 Agent 必须自检。 --- @@ -40,7 +40,7 @@ router → handler → service → repository → domain / model |---|---|---| | service → handler | 业务逻辑不得感知 HTTP | 已合规 | | repository → service / handler | 数据层不得承载业务 | 已合规 | -| middleware → repository | HTTP 横切层不得直捣存储(终态:依赖 IdentityProvider 抽象) | 仅 `identity.go` 实现 1 处 | +| middleware → repository | HTTP 横切层不得直捣存储(终态:依赖 IdentityProvider 抽象) | 已合规(`identity.go` 以包内窄接口 `userLookup` 收敛,见 `debt/architecture.md` 第 1 条) | | router → repository(仅为拼装中间件) | 路由层不应持有数据访问句柄 | router 依赖 repository 归零 | | 任何包 → `database.GetDB()` 全局单例 | 破坏可测试性 | 已合规(仅 `cmd/myblog` 与 `cmd/seed` 使用) | @@ -65,8 +65,11 @@ apps/web, apps/admin(组合根:实例化与回调注入) ```bash # 在 server/ 目录下执行(路径相对当前目录解析,在仓库根执行会得到零命中的假绿) -# 基线:service 12 + middleware 1(仅 identity.go)+ router 0 = 13 文件 -git grep -ln "MyBlog/internal/repository" -- internal/service internal/middleware internal/router ':(exclude)*_test.go' +# 基线:0 文件。middleware 与 router 均不得 import repository;service 消费仓储接口属允许边,不在此命令统计 +git grep -ln "MyBlog/internal/repository" -- internal/middleware internal/router ':(exclude)*_test.go' + +# 仓储的具体实现 struct 与构造函数只允许出现在 repository 包与组合根,在 server/ 下执行(应为空) +git grep -n "repository\.New" -- internal ':(exclude)*_test.go' # 前端:packages 反向依赖应用(应为空;在仓库根执行) git grep -ln "apps/web" -- packages @@ -196,7 +199,8 @@ git grep -n "NewRBACService()" -- server ``` 该逻辑是否被两个 app 使用? -├─ 是 → 必须进 packages(shared/http/api,认证域终态为独立 auth 包) +├─ 是 → 必须进 packages(纯逻辑进 shared/http/api,认证域为 auth 包, +│ 由 stock 组件组合的界面组件进 components 包) └─ 否 → 留在应用内 该逻辑与另一 app 现有代码是否同构? └─ 是 → 违反复用纪律,停下提取;否 → 正常开发 @@ -204,10 +208,10 @@ git grep -n "NewRBACService()" -- server 已知跨 app 重复文件分两档,处理方式不同: -1. **逐字重复,改任一必须同步另一份**(`git diff --no-index` 应零差异):`src/lib/stores/auth.ts`(15 行 ×2)、`src/lib/components/theme-toggle.svelte`(45 行 ×2)。 +1. **逐字重复,改任一必须同步另一份**(`git diff --no-index` 应零差异):`src/lib/stores/auth.ts`(10 行 ×2)。它是纯注入接缝,包内无法解析 `$lib/api`,故接缝留在应用侧并设 10 行上限。 2. **职责同构但内容不同,不计入逐字重复**,也不要求逐字同步:`service/index.ts`(69 / 67 行,差异在 `getLanguage` 取值与 `goto` 导入来源)、`routes/+layout.svelte`(20 / 12 行)、`routes/+error.svelte`(95 / 38 行,web 编辑杂志版式与 admin 居中版式已各自独立设计)。 -新增公共逻辑仍按 6.1 决策树优先下沉 packages;两档文件均不得再增加第三份同构实现。 +新增公共逻辑仍按 6.1 决策树优先下沉 packages;两档文件均不得再增加第三份同构实现。本轮 `theme-toggle.svelte` 由两应用副本收敛为 `packages/components/src/theme-toggle` 单一实现。 ### 6.2 数据加载 @@ -227,52 +231,61 @@ git grep -n "NewRBACService()" -- server - token pair 形状:`{accessToken, refreshToken, expiresIn}`。 - 线格式:**不透明令牌**(服务端签发 32 位十六进制随机串,身份与生命周期登记在服务端令牌表;令牌自身不携带任何可解码信息,校验以令牌表为唯一权威,不重构也不重新签名)。 - 刷新:`POST /api/auth/refresh`,body `{refreshToken}`;刷新即旋转(旧 refresh token 撤销),旋转前查库校验用户存在且状态正常。 -- 撤销:令牌表为内存 map(单实例前提);撤销即从表中移除记录,过期记录随签发惰性清理;登出撤销令牌对(refreshToken 经请求体可选提交),改密成功按用户撤销全部既有令牌。 +- 撤销:令牌表为内存 map(单实例终态前提,不迁移);撤销即从表中移除记录,过期记录随签发惰性清理;登出撤销令牌对(refreshToken 经请求体可选提交),改密成功按用户撤销全部既有令牌。 - access 链路取舍:信任短有效期,不逐请求查库;被禁用用户的存量 access 至多存活 `token.access_expire` 分钟,实时失效诉求由 Cookie 会话方案承接。 - 前端 401 识别:以响应体业务码 `code === 401` 判定(`TOKEN_ERROR_MESSAGES` 文案匹配已移除,禁止回退)。 --- -## 7. 部署形态与可用性约束(单实例) +## 7. 部署形态与可用性约束(单实例终态) -> 本节的取舍是**有意接受**的架构决策,不是待修复的缺陷:它记录当前形态能做什么、不能做什么,以及扩容前必须先完成的改造。 -> 代码事实来源:`docker-compose.yml`(五个服务各一份,无副本与故障转移)、`service/token.go`(进程内令牌表)、`middleware/ratelimit.go`(进程内计数 map)。 +> 本项目**确定不扩容**:应用进程、MySQL、网关各一份,全部部署于同一台服务器,由同一 nginx 实例按端口区分出入口,全球仅此一份。 +> 单实例是**终态**而非过渡形态,因此本节登记形态事实与由此产生的可用性后果,不构成待改造清单。 +> 代码事实来源:`docker-compose.yml`(各服务一份,无副本与故障转移)、`service/token.go`(进程内令牌表)、`middleware/ratelimit.go`(进程内计数 map)。 -### 7.1 当前约束 +### 7.1 形态事实与后果 -| 维度 | 当前形态 | 后果 | +| 维度 | 形态 | 后果 | |---|---|---| -| 部署形态 | 应用进程、MySQL、网关各**单实例** | 无横向扩容能力,单副本容量即整站容量 | -| 会话令牌 | 存于**进程内存**,不透明随机串,身份唯一权威在服务端令牌表 | **服务重启或发布导致全体用户登出**,发布窗口需提前预告用户 | -| 请求限流 | 进程内计数 map,按客户端 IP 或用户维度计数 | 阈值是**单进程**口径,多副本会使实际阈值成倍放大 | +| 部署形态 | 应用进程、MySQL、网关各一份,同一 nginx 实例按端口区分入口 | 无副本与故障转移,单份容量即整站容量 | +| 会话令牌 | 不透明随机串存于进程内存,身份唯一权威在服务端令牌表 | **服务重启或发布导致全体用户登出**,发布窗口需提前预告用户;令牌不跨进程共享 | +| 请求限流 | 进程内计数 map,按客户端 IP 或用户维度计数 | 阈值即**单进程**口径;进程重启后计数清零 | | 故障处理 | **无自动故障转移** | **故障即停站**,恢复依赖人工介入与重启;无 RTO 承诺,RPO 为 24 小时(见 `operations/backup-restore.md`) | -### 7.2 扩容前置改造三项 +### 7.2 变更前提(当前不触发) -三项须**全部完成**才能以增加副本的方式扩容,缺任一项即产生静默缺陷: +若未来改变"不扩容"的决定、改以增加副本方式扩容,须先完成下列两项,缺任一项即产生静默缺陷;在当前终态下两项均**不做**,因此它们不是待还债务: 1. **令牌表持久化**:把 `service/token.go` 的内存表切换到共享存储,并保持「查表即唯一权威」的既有校验语义。`model.AuthToken` 的 `TokenHash`(SHA256 十六进制)通道已就绪,可沿用该存储口径。 2. **限流器外置**:把 `middleware/ratelimit.go` 的进程内计数迁至共享存储,否则限流阈值随副本数成倍放大,防护形同失效。 -3. **反向代理信任链**:为 `gin.Engine` 补 `SetTrustedProxies` 配置(当前零配置)。缺此配置时经网关转发后 `ClientIP()` 恒为网关地址,同时影响限流、登录失败锁定、访问审计与 WAF 四项能力;`ClientIP()` 现有 7 处调用。 -### 7.3 验证命令 +### 7.3 代理信任链(已收敛) + +客户端 IP 的取值受 `security.trusted_proxies` 白名单约束,与副本数无关: + +- `internal/router/router.go` 在构造引擎时调用 `SetTrustedProxies`,只有列表内来源携带的 `X-Forwarded-For` 才参与解析,非受信来源的该头部被忽略。 +- 默认只信任本机回环;容器编排经 `MYBLOG_SECURITY_TRUSTED_PROXIES` 注入容器网段,漏配会让客户端 IP 退化为网关地址。 +- 历史缺陷、订正后的影响面与回归用例见 [`debt/security-runtime.md`](./debt/security-runtime.md) 第 4 条。 + +### 7.4 验证命令 ```bash -# 改造前两处均应为空 -git grep -n "SetTrustedProxies" -- server +# 应为空,确认单实例形态事实 git grep -n "replicas" -- docker-compose.yml +# 应命中 internal/router/router.go,确认信任链已接线 +git grep -n "SetTrustedProxies" -- server ``` --- -## 8. 债务登记表(基线只减不增) +## 8. 债务与取舍登记表(基线只减不增) -> 完整条目(状态、基线数值、验证命令、完整红线)按关注域分册登记在 `docs/debt/`,机制与维护流程见 [`debt/README.md`](./debt/README.md)。 -> 本节只保留索引:触碰相关区域前先按「所属分册」读对应条目,任务自检时核对基线不恶化。 +> 完整条目(状态、基线或上限、验证命令、红线)按关注域分册登记在 `docs/debt/`,机制与维护流程见 [`debt/README.md`](./debt/README.md)。 +> 本节只保留索引:触碰相关区域前先按「所属分册」读对应条目,任务自检时核对债务基线不恶化、已接受取舍不逾越上限。 -| 债务 | 所属分册 | 红线(一句话) | +| 条目 | 所属分册 | 红线(一句话) | |---|---|---| -| service/middleware/router import repository | [`debt/architecture.md`](./debt/architecture.md) 第 1 条 | 只减不增 | +| service/middleware/router import repository | [`debt/architecture.md`](./debt/architecture.md) 第 1 条 | middleware 与 router 不得 import repository;service 属允许边 | | router 重复定义 handler 接口 + `interface{}` 断言 | [`debt/architecture.md`](./debt/architecture.md) 第 2 条 | 禁止重新引入 | | `RBACService` 生产实例化 | [`debt/architecture.md`](./debt/architecture.md) 第 3 条 | 禁止新增实例化点 | | 双 User 模型同写 users 表 | [`debt/architecture.md`](./debt/architecture.md) 第 4 条 | 新字段只加 `domain.User` | @@ -290,8 +303,7 @@ git grep -n "replicas" -- docker-compose.yml | 公开端点直出实体泄漏个人信息 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 1 条 | 个人信息须经窄化 DTO 或字段白名单 | | 文章响应泄漏作者审计字段 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 2 条 | 新增审计字段默认 `json:"-"` | | WAF 内容级黑名单的固有误伤面 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 3 条 | 阻止模式必须先红后绿并配两组用例 | -| 令牌表为内存 map | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 4 条 | 单实例前提;持久化前保持锁 | -| 测试替身内嵌空接口的运行时脆性 | [`debt/testing.md`](./debt/testing.md) 第 1 条 | 受影响 fake 必须显式覆写 | +| 代理信任链未收敛导致 `ClientIP()` 可伪造 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 4 条 | 仅 `security.trusted_proxies` 内来源可参与解析,禁止回退为信任全部来源 | --- @@ -307,6 +319,8 @@ git grep -n "replicas" -- docker-compose.yml | 阶段三 契约切换 | handler DTO 分离;`contracts/` + 三把锁双向锚定(替代 codegen);401 改错误码判定 | 401 文案匹配与审计字段泄漏已修复;三把锁已落地(`pnpm run contract:check`) | ✅ 影子类型归零;漂移必当天变红 | | 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一;admin 胖组件行数口径 7→0,13 个页面取数归位到 load(含 11 个页面状态模块与配套单测),取数口径 6→0,`onMount` 仅余鉴权 2 处 | 权限定义全栈唯一;认证工具单轨 ✅;admin 行数与取数两条基线均归零 ✅ | | 阶段五 扩展点 | 后端 ContentRenderer 内容策略接口(当前 `pkg/markdown` 已直接承接 Markdown 渲染,策略接口化待做);web 业务页面已按"公开数据 SSR + 个性化数据客户端补拉"现状接入,token 迁 cookie 已完成 | — | 新文章类型 = 插入实现,非逐层打洞 | +| 阶段六 代理信任链收敛 | 引擎构造期接入信任链白名单;`NewRouter` 改为返回错误;配置校验拒绝覆盖全部地址的取值;补伪造转发头的四态用例 | 代理信任链未收敛导致 `ClientIP()` 可伪造(`docs/debt/security-runtime.md` 第 4 条) | ✅ 接线前实测三例失败且日志 `clientIp` 为伪造值;接线后伪造转发头不再影响 `ClientIP()` | +| 阶段七 依赖边口径订正 | 中间件在包内声明消费方窄接口,收敛对 repository 包的依赖;债务基线拆分为允许边与违例边,同步订正 §2.1、§2.3 与 CI 断言 | service/middleware/router import repository(`docs/debt/architecture.md` 第 1 条) | ✅ middleware 与 router 的违例 import 归零;查询参数留在 repository 经确认接受;CI 基线断言由 ≤13 改为 =0 | --- diff --git a/docs/debt/README.md b/docs/debt/README.md index 8019148..d40b011 100644 --- a/docs/debt/README.md +++ b/docs/debt/README.md @@ -1,33 +1,33 @@ -# 债务登记分册(docs/debt/) +# 债务与取舍登记分册(docs/debt/) -> 本目录是 `docs/architecture-rules.md` 第 8 节债务登记表的分册。第 8 节保留「债务名 | 所属文件 | 一句话红线」的索引表;完整条目(状态、基线数值、验证命令、完整红线)按关注域放在本目录。 +> 本目录是 `docs/architecture-rules.md` 第 8 节登记表的分册。第 8 节保留「条目 | 所属分册 | 一句话红线」的索引表;完整条目(状态、基线或上限、验证命令、红线)按关注域放在本目录。 +> 本目录同时登记两类事项:已清除的违例与取舍已定的架构决定。后者不构成债务,登记目的是把取舍理由、上限与前提固定下来,避免被反复重提为待修项。 ## 分组 | 分册 | 覆盖范围 | 条目数 | |---|---|---| | [`architecture.md`](./architecture.md) | 依赖方向、结构归位、类型真相源、模块对齐、错误语义归位 | 7 | -| [`frontend.md`](./frontend.md) | 两应用复用、认证工具、页面结构与取数、分页、i18n、UI 遗留 | 8 | -| [`security-runtime.md`](./security-runtime.md) | 公开端点隐私、审计字段、WAF、会话令牌运行时 | 4 | -| [`testing.md`](./testing.md) | 测试替身与测试纪律 | 1 | +| [`frontend.md`](./frontend.md) | 两应用复用、认证工具、页面结构与取数、分页、i18n、UI 交互 | 8 | +| [`security-runtime.md`](./security-runtime.md) | 公开端点隐私、审计字段、WAF、代理信任链 | 4 | -合计 20 条,与 `docs/architecture-rules.md` 第 8 节的索引表一一对应。 +合计 19 条,与 `docs/architecture-rules.md` 第 8 节的索引表一一对应。 > 相邻登记:契约与实现之间若再现映射冲突,登记在 `contracts/errors.yaml` 的「实现偏差」节,该节清除后自行删除;历史偏差(登录与刷新的私有 401 分支)已随 `architecture.md` 第 7 条修复一并清除。 ## 条目格式 -每条债务固定四个字段: +每条固定四个字段: -- **状态**:`已修复`、`已统一`、`存量`。标为存量的条目适用基线只减不增。 -- **基线**:当前实测数值与统计口径,含不计入统计的例外。 +- **状态**:`已修复`、`已统一`、`已接受`、`推进中`。`已修复` 与 `已统一` 记载已清除的结构性违例;`已接受` 表示取舍已定、不构成债务,条目只保留上限与前提;`推进中` 表示分期计划,按批次推进。 +- **基线**:当前实测数值与统计口径,含不计入统计的例外。已修复条目保留基线作为回归锚点;已接受条目不设基线,改为写明上限。 - **验证命令**:可直接执行的命令,或指向 `docs/architecture-rules.md` 的对应小节;命令必须写清执行目录与排除规则。 - **红线**:触碰相关区域时必须遵守的约束。 ## 维护纪律 -1. **基线只减不增**:任何改动使基线恶化(新增违例文件、新增实例化点、新增重复代码)即判定违规。 +1. **基线只减不增**:本纪律约束债务条目,任何改动使其基线恶化(新增违例文件、新增实例化点、新增重复代码)即判定违规;已接受条目改守其上限与前提,逾越上限或放弃前提同样判定违规。 2. **修复即登记**:修复一条债务须在同一变更内更新三处——本目录对应条目(状态与基线)、第 8 节索引表、`docs/architecture-rules.md` 第 9 节的分期状态。 -3. **不得以提交信息替代登记**:债务状态只以本目录与第 8 节为准。 -4. **新增债务**:先判断归属分册,按上述四字段写入对应文件,再补第 8 节索引行;无合适分册时新增分册并更新本文件的分组表。 +3. **不得以提交信息替代登记**:条目状态只以本目录与第 8 节为准。 +4. **新增条目**:先判断归属分册,按上述四字段写入对应文件,再补第 8 节索引行;无合适分册时新增分册并更新本文件的分组表。取舍条目须写明上限与前提,不得只写结论。 5. **验证命令必须实测**:写入前实际执行一次并确认输出与基线一致;执行目录或排除规则变化时必须写进条目,否则会产生假绿。 diff --git a/docs/debt/architecture.md b/docs/debt/architecture.md index ed21127..164faac 100644 --- a/docs/debt/architecture.md +++ b/docs/debt/architecture.md @@ -5,10 +5,12 @@ ## 1. service/middleware/router import repository -- **状态**:存量,只减不增。 -- **基线**:service **12** + middleware **1** + router **0**,合计 13 个文件。router 已归零,middleware 仅 `identity.go`;`*_test.go` 测试替身文件不计入。dict 模块接入曾使 service 层由 11 增至 12。 -- **验证命令**:见 `docs/architecture-rules.md` §2.3。必须在 `server/` 目录下执行(相对 pathspec 在仓库根执行会得到零命中的假绿),并带 `':(exclude)*_test.go'` 排除测试文件;不排除时命中数为 33。 -- **红线**:只减不增。 +- **状态**:已修复。 +- **基线**:违例边 **0** 个文件。`middleware → repository` 经消费方窄接口收敛——`identity.go` 的 `userLookup` 只声明 `GetByID` 一项能力,仓储实现由组合根注入后结构化满足;`router → repository` 早已归零。不排除 `*_test.go` 时命中 2 个测试替身文件(middleware 与 router 各 1)。 +- **允许边**:`service → repository` 属 `docs/architecture-rules.md` §2.1 允许图。service 消费 `repository.XxxRepositoryInterface` 时必然 import 该包,故 service 的 12 个文件不计入违例。首版基线将三者合并计为 13 个文件,实为 12 个允许边加 1 个违例边,口径随本次修复订正。 +- **已接受口径**:查询参数与结果结构(`ArticleListParams`、`ArticleArchiveGroup` 等 11 个)随接口声明在 repository 包,属接口签名的组成部分,不迁移至 `internal/domain`。 +- **验证命令**:见 `docs/architecture-rules.md` §2.3。必须在 `server/` 目录下执行(相对 pathspec 在仓库根执行会得到零命中的假绿),并带 `':(exclude)*_test.go'` 排除测试文件。 +- **红线**:`middleware` 与 `router` 不得 import repository;中间件消费存储能力一律在包内声明窄接口,实现由组合根注入。仓储的具体实现 struct 与 `New*Repository` 构造函数只允许出现在 repository 包与组合根,service 只可消费接口与查询参数。 ## 2. router 重复定义 handler 接口与 `interface{}` 断言 diff --git a/docs/debt/frontend.md b/docs/debt/frontend.md index 7abf28e..c0aef7b 100644 --- a/docs/debt/frontend.md +++ b/docs/debt/frontend.md @@ -5,15 +5,17 @@ ## 1. 两 app 基础设施逐字重复 -- **状态**:存量,只减不增。 -- **基线**:逐字重复仅 **2 文件 60 行**:`src/lib/stores/auth.ts`(15 行 ×2,SHA256 一致)与 `src/lib/components/theme-toggle.svelte`(45 行 ×2,SHA256 一致)。另有 3 文件职责同构但内容不同,不计入逐字重复:`service/index.ts`(69 / 67 行)、`routes/+layout.svelte`(20 / 12 行)、`routes/+error.svelte`(95 / 38 行,两 app 版式已各自独立设计)。 -- **验证命令**:`git diff --no-index apps/web/src/lib/stores/auth.ts apps/admin/src/lib/stores/auth.ts`(应为零差异);同法核对 `theme-toggle.svelte`。 -- **红线**:修改任一逐字重复文件必须同步另一份;禁止新增逐字或近似重复文件,公共逻辑下沉 packages。 +- **状态**:已接受。取舍已定,不构成债务:接缝必须留在应用侧,因为 `packages/auth` 内无法解析 `$lib/api`;上限 10 行,超出即按复制粘贴式共享返工。 +- **上限**:逐字重复仅 `src/lib/stores/auth.ts`(10 行 ×2,SHA256 一致)。它是纯注入接缝:`packages/auth` 的 `createAuthStore` 需要 `logoutApi`,而 `$lib/api` 是应用别名、包内无法解析,故接缝必须留在应用侧,**上限 10 行**,超出即按复制粘贴式共享返工。 + - 本轮收敛:`theme-toggle.svelte`(45 行 ×2)下沉至 `packages/components/src/theme-toggle`,两应用副本与 `lib/components/index.ts` 桶一并删除,消费点改为按包名 `@myblog/components/theme-toggle` 导入;应用侧 `isBrowser` 注入移除,环境判定改由包内复用 `@myblog/shared` 的 `isBrowser`。 + - 另有 3 文件职责同构但内容不同,不计入逐字重复:`service/index.ts`(69 / 67 行)、`routes/+layout.svelte`(20 / 12 行)、`routes/+error.svelte`(95 / 38 行,两 app 版式已各自独立设计)。 +- **验证命令**:`git diff --no-index apps/web/src/lib/stores/auth.ts apps/admin/src/lib/stores/auth.ts`(应为零差异);`git ls-files "*theme-toggle.svelte"` 应仅命中 `packages/components` 一处;形态解析用例经 `pnpm run test:packages` 覆盖。 +- **红线**:修改任一逐字重复文件必须同步另一份,且该接缝不得超过 10 行;禁止新增逐字或近似重复文件,公共逻辑下沉 packages,跨应用组合组件下沉 `packages/components`。 ## 2. admin 认证工具三轨并行 - **状态**:已统一。 -- **基线**:`utils/jwt.ts`、`utils/auth.ts` 已删(约 488 行);`lib/utils` 现仅 `auth-guard.ts`(路由守卫 `requireAuth`)、`logout.ts`(`performLogout`)、`navigation.ts`、`permissions.ts` 四个文件;刷新单轨在 `service/index.ts`。 +- **基线**:`utils/jwt.ts`、`utils/auth.ts` 已删(约 488 行);`lib/utils` 现为 6 个文件:`auth-guard.ts`(路由守卫 `requireAuth`)、`logout.ts`(`performLogout`)、`navigation.ts`、`permissions.ts`、`tag-display.ts`(标签状态展示解析,列表与表格组件共用同一降级口径)与 `__tests__/tag-display.test.ts`;刷新单轨在 `service/index.ts`。 - **验证命令**:`git ls-files apps/admin/src/lib/utils`(应无 `jwt.ts`、`auth.ts`);`git grep -n "manualRefreshToken\|getAuthStatus" -- apps/admin/src`(应为空)。 - **红线**:禁止新增认证工具文件;禁止双轨回退。 @@ -45,14 +47,14 @@ ## 6. admin 重写 `$ui` 已有组件(含 web 侧分页例外) -- **状态**:admin 侧已修复;web 侧分页为受接受存量。 +- **状态**:admin 侧已修复;web 侧分页为已接受取舍。 - **基线**:admin 本地 `pagination.svelte` 已删,7 页回归 `$ui`。web 侧保留 `apps/web/src/lib/components/article/PaginationNav.svelte` 的锚点版式,以产出可被爬虫与无 JavaScript 环境跟随的真实 ``。原登记的技术阻塞「`$ui` 包装层未透传 bits-ui 的 `child` 元素替换通道」经复核**不成立**:`pagination-link.svelte` 未解构 `child`,该属性随 `...restProps` 透传至 `PaginationPrimitive.Page`,且 bits-ui 的 Page/PrevButton/NextButton 类型均带 `WithChild`;若要统一,先实测确认后再迁移。 - **验证命令**:读 `packages/ui/src/pagination/pagination-link.svelte` 的 `...restProps` 透传与 bits-ui 类型的 `WithChild`;`git grep -n "child" -- packages/ui/src/pagination` 的命中均为 `children` 通道,不能作为透传缺口的证据。 - **红线**:admin 侧禁止仿效;新分页一律 `$ui`;web 侧在该项统一前不得新增第三处分页实现。 ## 7. web 界面多语言局部接入 -- **状态**:存量,分批推进。 +- **状态**:推进中,分批接入。 - **基线**:语言切换对 Header、Footer、错误页真实生效(含 NotificationBell、FriendlyLinkDialog 两个 Header 子组件与 demo 页),其余页面文案硬编码中文,en 模式下界面为混合语言;词表文件必须保持 JSON 兼容写法(paraglide 编译器按严格 JSON 解析,json5 特性直接编译失败)。 - **验证命令**:`git grep -ln "\$i18n" -- apps/web/src`(已接入面:Header、Footer、NotificationBell、FriendlyLinkDialog、`+error`、demo)。 - **红线**:已接入文件禁止回退硬编码;新增用户可见文案优先经 `m.*` 词表取词;其余页面接入待页面大变动后分批推进。 diff --git a/docs/debt/security-runtime.md b/docs/debt/security-runtime.md index 4fbf052..807feb6 100644 --- a/docs/debt/security-runtime.md +++ b/docs/debt/security-runtime.md @@ -31,9 +31,14 @@ 2. 正文豁免以渲染层消毒为前提,扩大豁免清单前必须确认该字段的每一处输出都经消毒渲染或转义输出; 3. 删除或放宽渲染层消毒(`pkg/markdown` 的 `Unsafe`、`apps/web` 的 `renderMarkdown`)时,必须同步收回对应的正文豁免。 -## 4. 令牌表为内存 map +## 4. 代理信任链未收敛导致 `ClientIP()` 可伪造 -- **状态**:存量,单实例部署前提。 -- **基线**:已加锁并支持过期惰性清理(`sync.RWMutex` 保护,过期记录随签发清理);令牌为服务端签发的不透明随机串,身份唯一权威在服务端令牌表。 -- **验证命令**:`git grep -n "tokensByUser" -- server`。 -- **红线**:持久化前保持锁;服务重启即全部会话失效;多副本部署前必须先完成持久化改造(见 `docs/architecture-rules.md` §7.2)。 +- **状态**:已修复(信任链收敛为白名单,配置项 `security.trusted_proxies`)。 +- **基线**: + - `internal/router/router.go` 在构造引擎后立即调用 `engine.SetTrustedProxies(cfg.Security.TrustedProxies)`,取值非法时返回错误并由组合根在启动期终止;`NewRouter` 相应改为返回 `(*Router, error)`。 + - 受信来源唯一权威为 `security.trusted_proxies`,代码默认只信任 `127.0.0.1/32` 与 `::1/128`;容器编排经 `MYBLOG_SECURITY_TRUSTED_PROXIES` 按逗号分隔注入容器网段,compose 默认注入 `172.16.0.0/12`。 + - 配置校验拒绝空项、非法 IP 或 CIDR,以及 `0.0.0.0/0` 与 `::/0` 这类覆盖全部地址的取值,避免回退为信任全部来源。 + - 回归用例:`internal/router/router_trusted_proxy_test.go` 覆盖四态——非受信来源携带伪造 `X-Forwarded-For` 时取连接来源地址、经受信代理转发时取最右侧非受信地址、受信代理单值转发被采信、信任列表为空时一律取连接来源地址;`internal/config/config_test.go` 覆盖非法项与覆盖全部地址的拒绝、环境变量注入与空值语义。接线前实测三例失败,日志字段 `clientIp` 为伪造值。 + - 早前登记的表述已订正:既非「经网关转发后 `ClientIP()` 恒为网关地址」,也非「影响限流、登录失败锁定、访问审计与 WAF 四项」。实际受影响面为 IP 级限流、审计 IP 落库、未登录访客去重键与管理员接口 IP 白名单;登录失败锁定按用户 ID 落库,WAF 无 IP 黑名单,二者均不受影响。 +- **验证命令**:`git grep -n "SetTrustedProxies" -- server` 应恰好命中 `internal/router/router.go` 一处实现(README 说明性命中不计);`go test ./internal/router/ ./internal/config/ -count=1`。 +- **红线**:仅 `security.trusted_proxies` 内的来源可参与 `ClientIP()` 解析;禁止回退为信任全部来源,禁止在配置校验中放行覆盖全部地址的取值;新增按 IP 的安全判定一律基于 `ClientIP()`,不得自行解析转发头。 diff --git a/docs/debt/testing.md b/docs/debt/testing.md deleted file mode 100644 index 9ff08ab..0000000 --- a/docs/debt/testing.md +++ /dev/null @@ -1,11 +0,0 @@ -# 债务登记:测试纪律 - -> 本文件是 `docs/architecture-rules.md` 第 8 节债务登记表的「测试纪律」分册。 -> 通用机制、条目字段含义与维护流程见 [`README.md`](./README.md)。 - -## 1. 测试替身内嵌空接口的运行时脆性 - -- **状态**:存量约定,三处实证。 -- **基线**:service 层 fake 以内嵌接口继承全部方法,接口新增方法被既有测试路径调用时以 nil panic 暴露而非编译错误;已实证三例:`recordedTokenService.GenerateTokenPair`、`loginUserRepo.Update`、`lockoutUserRepo.GetByUsername`。 -- **验证命令**:`go test ./internal/... -count=1`。 -- **红线**:接口新增方法被既有测试路径触达时,必须为受影响 fake 显式覆写,禁止依赖内嵌空接口的静默兼容。 diff --git a/docs/development.md b/docs/development.md index 7d01d15..c58d4c8 100644 --- a/docs/development.md +++ b/docs/development.md @@ -141,7 +141,7 @@ apps/admin/src/ # 后台 #### 关键技术配置 - 路径别名见各应用 `svelte.config.js`:`$ui` 与 `$ui/*`(指向 `packages/ui/src` 源码)、`@/*`(应用自身 `src`);`$lib` 由 SvelteKit 隐式提供,未在配置中声明;前台另有 `$i18n`(指向 `src/lib/paraglide/messages`)。`svelte.config.js` 与 `tsconfig.json` 均未声明 `#/*` 或 `~/*` 别名;前台 `vite.config.ts` 的构建期别名只有 `#fonts`(dev 走本地 fontsource、prod 走 CDN 模块),与通配形态的 `#/*` 不是一回事。 -- `packages/ui` 以**源码直连**方式被引用,各应用在 `vite.config.ts` 配置 `ssr.noExternal: ['@myblog/ui']` 参与 SSR 编译;Tailwind v4 在各应用 `app.css` 用 `@source` 显式纳入 `packages/ui/src` 扫描。 +- `packages/ui` 与 `packages/components` 均以**源码直连**方式被引用,各应用在 `vite.config.ts` 配置 `ssr.noExternal: ['@myblog/ui', '@myblog/components']` 参与 SSR 编译;Tailwind v4 在各应用 `app.css` 用 `@source` 显式纳入 `packages/ui/src` 与 `packages/components/src` 扫描。前者经 `$ui` 别名引用,后者按包名 `@myblog/components/` 引用,不设应用别名。 - 后台在 `svelte.config.js` 配置 `paths.base = '/admin'` 与 `relative: false`,与前台同源区分部署。 - 前台经 `@inlang/paraglide-js` 做 i18n,产物位于 `src/lib/paraglide`;后台不引入 i18n。 - 两应用均使用 `unplugin-auto-import` 自动导入 SvelteKit / Svelte / toast 常用函数。 @@ -579,6 +579,7 @@ pnpm run build:web # 构建前端静态文件 - **架构铁律**: 依赖方向、类型唯一真相源等结构性约束见 [`architecture-rules.md`](./architecture-rules.md) - **事务化模式**: 多段写库必须包裹单事务;repository 提取 `xxxTx(db *gorm.DB, ...)` 私有方法供事务与独立公开方法复用(`createTx`/`syncTagsTx`/`syncCategoriesTx`/`updateTx`/`recordArticleView` 先例,事务内所有查询与写入均走事务句柄,禁止混用 `r.db`),跨仓储共享的写逻辑下沉为包内共享 helper(`upsertContentStat` 先例),不引入仓储间依赖 - **安全配置默认值双源对齐**: `security.login_lockout` 的 viper 默认值与 service 层 `defaultLoginLockoutPolicy` 必须一致(5 次 / 15 分钟),修改任一处必须同步另一处 +- **代理信任链取值三处一致**: `security.trusted_proxies` 的代码默认值(`defaultTrustedProxies`)、`configs/config.yaml` 与 `configs/config.example.yaml` 声明值必须一致(默认仅回环),容器编排的取值写在 `docker-compose.yml` 的 `MYBLOG_SECURITY_TRUSTED_PROXIES`,改动代理来源时必须三处同步,漏改会让客户端 IP 归并到网关地址 ### 2. 错误处理 @@ -618,18 +619,18 @@ pnpm run build:web # 构建前端静态文件 - **sqlmock 维护**: repository 层 sqlmock 断言与 GORM 生成的 SQL 文本强耦合,GORM 升级或查询改写时须同步维护期望;匹配 SQL 用 `regexp.QuoteMeta` 前缀正则,期望序列须与事务内实际步骤(含 DELETE、计数 UPDATE)完全一致,否则以"剩余期望未匹配"失败 - **契约金样本维护**: 金样本须与 Go 响应逐字节一致(`json.Compact` 豁免空白),修改实现输出字段时必须同步修订金样本并跑 `contract:check`。易错点:`datetime.JSONDate` 序列化为零值 `null`、午夜日期-only、非午夜 `"2006-01-02 15:04:05"`(非 RFC3339);`gin.H` map 序列化按字典序排键;Go `encoding/json` 默认 HTML 转义(`<` `>` 输出 `\u003c`),金样本取值应避开尖括号;`omitempty` 对 nil 指针与空切片省略键;内嵌结构体的同名字段被外层结构体遮蔽时按索引序输出,恢复字段会排在内嵌字段之后。锁②为 `WidenLiteral`+`toExtend` 单向合法实例校验(JSON 单值无法与 nullable 联合精确相等,见 architecture-rules.md §3.4)。新增金样本必须同时补 Go 断言与 TS 锚点,`TestFixtureCoverage` 会校验目录与双端锚点一一对应 - **gin 中间件测试**: 中间件函数内 `return` 不会中断 gin 的 handler 链,中断必须调用 `c.Abort()`;`IdentityProvider.Resolve` 失败时由实现写响应并 `Abort`,消费方 `if err != nil { return }` 依赖此语义,测试替身须模拟"写响应 + Abort"而非裸返错误。统一响应信封固定 HTTP 200,权限/认证失败以响应体业务码(`code` 字段)断言,不比较 HTTP 状态码 -- **依赖基线检查**: 相对 pathspec 必须在 `server/` 下执行:`git grep -ln "MyBlog/internal/repository" -- internal/service internal/middleware internal/router ':(exclude)*_test.go'`。在仓库根用同一段相对 pathspec 会零命中而得到假绿,仓库根执行须改写为 `-- server/internal/service server/internal/middleware server/internal/router ':(exclude)*_test.go'`。基线 **13 个文件**(service 12 + middleware 仅 `identity.go` + router 0),只减不增;`*_test.go` 须排除,否则计数会包含测试替身文件 +- **依赖基线检查**: 相对 pathspec 必须在 `server/` 下执行:`git grep -ln "MyBlog/internal/repository" -- internal/middleware internal/router ':(exclude)*_test.go'`。在仓库根用同一段相对 pathspec 会零命中而得到假绿,仓库根执行须改写为 `-- server/internal/middleware server/internal/router ':(exclude)*_test.go'`。基线 **0 个文件**(middleware 与 router 均不得 import repository;`service → repository` 属允许边,不计入);`*_test.go` 须排除,否则计数会包含 2 个测试替身文件 ### 5.1 质量门禁 - **契约门禁**: `pnpm run contract:check` = Go handler fixture 测试(锁①)+ `@myblog/api` 的 `tsc --noEmit`(锁② typecheck)+ vitest 类型锚定;契约相关改动必须通过 -- **CI**: `.github/workflows/ci.yml` 为质量门禁流水线,触发方式为 push 到 master/main 以及所有 pull request;步骤依次为 checkout、setup-node 22 + corepack、setup-go(读 `server/go.mod`)、`pnpm install --frozen-lockfile`、后端 go 三连(`go build` / `go vet` / `go test -count=1`)、`go:vulncheck`、`audit:deps`、依赖方向基线 grep(在 `server/` 内执行并断言命中数 ≤ 13)、`test:packages`、生成前台 i18n 产物(`pnpm --filter @myblog/web run generate:i18n`)、`test:apps`、`check`、`contract:check`、`build:apps`、`measure:assets`、`check:fonts`、`format:check`、`lint`;工作流不含自动部署步骤 +- **CI**: `.github/workflows/ci.yml` 为质量门禁流水线,触发方式为 push 到 master/main 以及所有 pull request;步骤依次为 checkout、setup-node 22 + corepack、setup-go(读 `server/go.mod`)、`pnpm install --frozen-lockfile`、后端 go 三连(`go build` / `go vet` / `go test -count=1`)、`go:vulncheck`、`audit:deps`、依赖方向基线 grep(在 `server/` 内执行并断言违例边命中数为 0)、`test:packages`、生成前台 i18n 产物(`pnpm --filter @myblog/web run generate:i18n`)、`test:apps`、`check`、`contract:check`、`build:apps`、`measure:assets`、`check:fonts`、`format:check`、`lint`;工作流不含自动部署步骤 - **依赖漏洞扫描**: Go 侧经 `pnpm run go:vulncheck` 运行固定版本的 `govulncheck`,判定口径为「存在可达调用链即失败」;前端与工具链侧经 `pnpm run audit:deps` 运行 `pnpm audit`,按 high/critical 阻塞、medium 及以下告警的阈值执行。扫描数据源与已知漏洞的收敛清单见 `scripts/README.md`;依赖升级由 `.github/dependabot.yml` 按周提交 PR ### 6. 可维护性 - **文档更新**: 架构规则变更时按 [`architecture-rules.md`](./architecture-rules.md) 同步规则本体与第 8 节债务索引;债务条目的状态与基线数值按 [`debt/README.md`](./debt/README.md) 的维护纪律更新对应分册,历史分期状态更新第 9 节 -- **自动化测试**: 后端关键逻辑配套 `*_test.go`(service/repository 层已有存量);前端 packages 公共逻辑与页面状态模块应补 `*.test.ts`。应用侧单测经根 `test:apps` 汇聚(`@myblog/web` 覆盖 markdown 渲染守卫、日期格式化与服务端会话 Cookie 转发,`@myblog/admin` 覆盖 11 个页面状态模块),并与 `test:packages` 一样纳入 `pnpm run test` 与 CI。 +- **自动化测试**: 后端关键逻辑配套 `*_test.go`(service/repository 层已有存量);前端 packages 公共逻辑与页面状态模块应补 `*.test.ts`(`@myblog/components` 覆盖主题切换组件的形态与名称解析)。应用侧单测经根 `test:apps` 汇聚(`@myblog/web` 覆盖 markdown 渲染守卫、日期格式化与服务端会话 Cookie 转发,`@myblog/admin` 覆盖 11 个页面状态模块),并与 `test:packages` 一样纳入 `pnpm run test` 与 CI。 - **测试文件位置**: 前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录(例如 `apps/admin/src/lib/utils/__tests__/tag-display.test.ts`);跨用例共享的测试替身与夹具置于包内 `src/test/`(例如 `packages/auth/src/test/fixtures.ts`),不放入 `__tests__/`。移动测试文件后须同步修正其相对导入层级,并检查写死测试文件路径的外部锚点(如 `server/internal/handler/fixture_coverage_test.go` 的 TS 锚点常量)。 ## 更多资源 diff --git a/docs/ui-design-system.md b/docs/ui-design-system.md index a32d27f..ec70881 100644 --- a/docs/ui-design-system.md +++ b/docs/ui-design-system.md @@ -29,10 +29,11 @@ - 聚合入口的代价是可量化的:包内 `packages/ui/src` 共 394 个文件,其中 334 个是 `.svelte`,类型检查需要逐个转换 `.svelte`;按两个应用实际引用的 24 个组件入口做静态可达分析,可达文件为 166 个(其中 `.svelte` 142 个)。 - 导入形态与组件的部件结构对齐:单部件组件用具名导入,例如 `import { Input } from '$ui/input'`;多部件组件用命名空间导入,例如 `import * as Card from '$ui/card'`,内部按 `` / `` 使用。 - `Chart` 组件在服务端渲染时会抛出运行时错误,需要时按子路径 `$ui/chart` 单独引用。 +- **组合组件不进入本包**:由 stock 组件组合、两应用共用的组件归属 `packages/components`,按包名 `@myblog/components/` 导入(不设应用别名),例如 `theme-toggle`;该包只做组合,同样禁止硬编码业务色,外观仍经各应用 token 与调用处 `className` 定制。`packages/ui` 只收 shadcn 库存件,新增一律在包内执行 CLI。 ### 1.3 主题注入机制(三件套) -任一应用引用 `packages/ui` 源码直连组件时,必须同时具备以下三项,缺一会导致「类不生成」或「SSR 报错」: +任一应用引用 `packages/ui` 源码直连组件时,必须同时具备以下三项,缺一会导致「类不生成」或「SSR 报错」;`packages/components` 的组件同样以源码直连,除别名一项外(该包按包名导入)同样需要 `ssr.noExternal` 与 `app.css` 的 `@source`: 1. **`svelte.config.js` 别名**:`$ui` → `../../packages/ui/src`,`$ui/*` → `../../packages/ui/src/*`。 2. **`vite.config.ts`**:`ssr.noExternal: ['@myblog/ui']`,使 `.svelte` 源码参与 SSR 编译。 diff --git a/package.json b/package.json index 7804143..aa8e5a1 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,7 @@ "check:fonts": "tsx scripts/check-font-bundle.ts", "test": "pnpm run test:server && pnpm run test:packages && pnpm run test:apps && pnpm run contract:check", "test:server": "tsx scripts/go-tools.ts test", - "test:packages": "pnpm --filter @myblog/api --filter @myblog/auth --filter @myblog/http run typecheck && pnpm --filter @myblog/api --filter @myblog/auth --filter @myblog/http run test", + "test:packages": "pnpm --filter @myblog/api --filter @myblog/auth --filter @myblog/components --filter @myblog/http run typecheck && pnpm --filter @myblog/api --filter @myblog/auth --filter @myblog/components --filter @myblog/http run test", "test:apps": "pnpm -r --parallel --stream --filter @myblog/web --filter @myblog/admin run test", "typecheck:web": "pnpm -r --parallel --stream --filter @myblog/web --filter @myblog/admin run check", "lint": "pnpm run lint:web && pnpm run lint:server", diff --git a/packages/auth/src/__tests__/auth-store.test.ts b/packages/auth/src/__tests__/auth-store.test.ts index e12c992..fc664ca 100644 --- a/packages/auth/src/__tests__/auth-store.test.ts +++ b/packages/auth/src/__tests__/auth-store.test.ts @@ -5,11 +5,11 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import type { User } from '@myblog/api/modules/user/types' import { get } from 'svelte/store' -// 构造注入依赖的最小替身,浏览器判定恒为 false 以隔离 localStorage。 +// 构造注入依赖的最小替身:测试默认运行于无 window 的 Node 环境, +// 包内环境判定为 false,因此不会触碰 localStorage。 function createTestStore(overrides?: Partial) { const logoutApi = vi.fn(async () => {}) const deps: AuthStoreDeps = { - isBrowser: () => false, logoutApi, ...overrides } @@ -17,13 +17,11 @@ function createTestStore(overrides?: Partial) { } // 构造接入浏览器环境替身的 store,用于持久化与跨标签页同步相关用例。 +// 环境替身必须在创建 store 之前安装,否则跨标签页同步监听不会注册。 function createBrowserStore() { const env = installFakeBrowserEnv() const logoutApi = vi.fn(async () => {}) - const store = createAuthStore({ - isBrowser: () => true, - logoutApi - }) + const store = createAuthStore({ logoutApi }) return { store, env, logoutApi } } @@ -65,10 +63,7 @@ describe('登录与持久化', () => { const env = installFakeBrowserEnv() env.seedSession({ userId: 3, username: 'user3', permissions: ['article:read'] }) - const store = createAuthStore({ - isBrowser: () => true, - logoutApi: async () => {} - }) + const store = createAuthStore({ logoutApi: async () => {} }) const state = get(store) expect(state.isAuthenticated).toBe(true) diff --git a/packages/auth/src/auth-store.ts b/packages/auth/src/auth-store.ts index ba06dd9..426a667 100644 --- a/packages/auth/src/auth-store.ts +++ b/packages/auth/src/auth-store.ts @@ -1,6 +1,6 @@ import type { User } from '@myblog/api/modules/user/types' +import { isBrowser, local } from '@myblog/shared' import { writable } from 'svelte/store' -import { local } from '@myblog/shared' // 认证状态接口。 // 会话令牌经 HttpOnly Cookie 由浏览器自动携带,前端不再持有任何令牌, @@ -13,14 +13,10 @@ export interface AuthState { /** * 认证 store 依赖注入集合。 - * 应用层负责提供环境判定与登出接口,避免包内耦合 SvelteKit 环境与页面路由。 + * 环境判定由包内经 @myblog/shared 的特性检测完成,应用层只需提供登出接口, + * 避免包内耦合 SvelteKit 环境与页面路由。 */ export interface AuthStoreDeps { - /** - * 判断当前是否运行于浏览器环境,SSR 阶段禁止访问 localStorage。 - */ - isBrowser: () => boolean - /** * 调用后端登出接口,服务端撤销令牌并清除会话 Cookie。 */ @@ -59,7 +55,7 @@ export function createAuthStore(deps: AuthStoreDeps) { // 从 localStorage 加载初始状态。 // 仅凭本地用户信息判定登录态,会话 Cookie 是否有效由首次请求的服务端裁决。 function loadInitialState(): AuthState { - if (!deps.isBrowser()) return initialState + if (!isBrowser()) return initialState try { const user = local.get(AUTH_USER_KEY) @@ -93,7 +89,7 @@ export function createAuthStore(deps: AuthStoreDeps) { // 清除本地存储中的全部认证状态。 function clearLocalStorage() { - if (!deps.isBrowser()) return + if (!isBrowser()) return local.rm(AUTH_USER_KEY) local.rm(AUTH_PERMISSIONS_KEY) } @@ -104,7 +100,7 @@ export function createAuthStore(deps: AuthStoreDeps) { * 任一标签页登出后,其余标签页必须跟随,避免展示已失效的登录态。 */ function syncFromStorage() { - if (!deps.isBrowser()) return + if (!isBrowser()) return const nextState = loadInitialState() if (isSameAuthState(currentState, nextState)) return @@ -113,7 +109,7 @@ export function createAuthStore(deps: AuthStoreDeps) { } // 注册跨标签页同步监听。storage 事件仅在写入方之外的同源标签页触发,因此不会形成回环。 - if (deps.isBrowser()) { + if (isBrowser()) { window.addEventListener('storage', event => { // 整库清空时 event.key 为 null,此时无法按键过滤,同样需要重新加载。 if (event.key === null || AUTH_STORAGE_KEYS.has(event.key)) { @@ -138,7 +134,7 @@ export function createAuthStore(deps: AuthStoreDeps) { permissions } - if (deps.isBrowser()) { + if (isBrowser()) { local.set(AUTH_USER_KEY, user) local.set(AUTH_PERMISSIONS_KEY, permissions) } @@ -148,7 +144,7 @@ export function createAuthStore(deps: AuthStoreDeps) { // 登出,先尝试撤销服务端会话再清除本地状态。 async logout(skipApiCall: boolean = false) { - if (!skipApiCall && deps.isBrowser() && currentState.isAuthenticated) { + if (!skipApiCall && isBrowser() && currentState.isAuthenticated) { try { await deps.logoutApi() console.log('成功调用后端登出接口') @@ -175,7 +171,7 @@ export function createAuthStore(deps: AuthStoreDeps) { update(state => { const newState = { ...state, user } - if (deps.isBrowser()) { + if (isBrowser()) { local.set(AUTH_USER_KEY, user) } diff --git a/packages/components/package.json b/packages/components/package.json new file mode 100644 index 0000000..5a30e26 --- /dev/null +++ b/packages/components/package.json @@ -0,0 +1,30 @@ +{ + "name": "@myblog/components", + "version": "0.0.0", + "private": true, + "type": "module", + "description": "MyBlog 跨应用组合组件:由 @myblog/ui 的 stock 组件组合而成,供前台与后台共用,不承载应用专属样式与业务状态。", + "exports": { + "./*": "./src/*/index.ts" + }, + "scripts": { + "test": "vitest run", + "test:watch": "vitest", + "typecheck": "svelte-check --tsconfig ./tsconfig.json" + }, + "dependencies": { + "@lucide/svelte": "catalog:", + "@myblog/shared": "workspace:*", + "@myblog/ui": "workspace:*", + "mode-watcher": "catalog:" + }, + "peerDependencies": { + "svelte": "catalog:" + }, + "devDependencies": { + "svelte": "catalog:", + "svelte-check": "catalog:", + "typescript": "catalog:", + "vitest": "catalog:" + } +} diff --git a/packages/components/prettier.config.js b/packages/components/prettier.config.js new file mode 100644 index 0000000..f8b1ae1 --- /dev/null +++ b/packages/components/prettier.config.js @@ -0,0 +1,21 @@ +import basePrettierConfig from '../../prettier.config.js' + +// 包内含 .svelte 组件,需在基础配置上补 Svelte 解析器与该语法的既定排版口径。 +// 口径与两个应用的 prettier 配置保持一致,避免同一组件在不同目录下排版不同。 +/** @type {import('prettier').Config} */ +const componentsPrettierConfig = { + ...basePrettierConfig, + svelteAllowShorthand: true, + svelteIndentScriptAndStyle: false, + plugins: ['prettier-plugin-svelte', 'prettier-plugin-css-order', 'prettier-plugin-sort-imports'], + overrides: [ + { + files: '*.svelte', + options: { + parser: 'svelte' + } + } + ] +} + +export default componentsPrettierConfig diff --git a/packages/components/src/theme-toggle/__tests__/toggle-variant.test.ts b/packages/components/src/theme-toggle/__tests__/toggle-variant.test.ts new file mode 100644 index 0000000..bb608dc --- /dev/null +++ b/packages/components/src/theme-toggle/__tests__/toggle-variant.test.ts @@ -0,0 +1,43 @@ +// 主题切换按钮的形态与名称解析单元测试。 +// 覆盖默认值回退与 outline 专属装饰两条分支。 +import { + DEFAULT_TOGGLE_LABEL, + DEFAULT_TOGGLE_VARIANT, + resolveToggleDecoration, + resolveToggleLabel, + resolveToggleVariant +} from '../toggle-variant' +import { describe, expect, it } from 'vitest' + +describe('无障碍名称解析', () => { + it('未传入名称时回退默认名称', () => { + expect(resolveToggleLabel()).toBe(DEFAULT_TOGGLE_LABEL) + }) + + it('传入名称时原样返回', () => { + expect(resolveToggleLabel('Toggle theme')).toBe('Toggle theme') + }) +}) + +describe('形态解析', () => { + it('未传入形态时回退默认形态', () => { + expect(resolveToggleVariant()).toBe(DEFAULT_TOGGLE_VARIANT) + }) + + it('传入形态时原样返回', () => { + expect(resolveToggleVariant('ghost')).toBe('ghost') + }) +}) + +describe('形态专属装饰', () => { + it('outline 形态附带边框与阴影装饰', () => { + const decoration = resolveToggleDecoration('outline') + + expect(decoration).toContain('border') + expect(decoration).toContain('shadow-md') + }) + + it('ghost 形态不附带装饰,交由按钮自身悬停反馈', () => { + expect(resolveToggleDecoration('ghost')).toBeUndefined() + }) +}) diff --git a/packages/components/src/theme-toggle/index.ts b/packages/components/src/theme-toggle/index.ts new file mode 100644 index 0000000..96aa956 --- /dev/null +++ b/packages/components/src/theme-toggle/index.ts @@ -0,0 +1,11 @@ +import ThemeToggle from './theme-toggle.svelte' + +export { ThemeToggle } +export { + DEFAULT_TOGGLE_LABEL, + DEFAULT_TOGGLE_VARIANT, + resolveToggleDecoration, + resolveToggleLabel, + resolveToggleVariant, + type ToggleVariant +} from './toggle-variant' diff --git a/packages/components/src/theme-toggle/theme-toggle.svelte b/packages/components/src/theme-toggle/theme-toggle.svelte new file mode 100644 index 0000000..105ef08 --- /dev/null +++ b/packages/components/src/theme-toggle/theme-toggle.svelte @@ -0,0 +1,38 @@ + + + diff --git a/packages/components/src/theme-toggle/toggle-variant.ts b/packages/components/src/theme-toggle/toggle-variant.ts new file mode 100644 index 0000000..46b9e2f --- /dev/null +++ b/packages/components/src/theme-toggle/toggle-variant.ts @@ -0,0 +1,29 @@ +// 主题切换按钮的变体与无障碍名称解析。 +// 与组件文件分离,使降级规则可被单测直接覆盖。 + +// outline 保留边框阴影供独立浮动场景使用,ghost 供导航栏与相邻图标按钮统一视觉。 +export type ToggleVariant = 'ghost' | 'outline' + +// 未传入 label 时使用的默认无障碍名称。 +export const DEFAULT_TOGGLE_LABEL = '切换主题' + +// 缺省形态取 outline,供登录页等独立浮动场景直接使用。 +export const DEFAULT_TOGGLE_VARIANT: ToggleVariant = 'outline' + +// 边框与阴影属于 outline 专属装饰,ghost 形态下由 Button 自身的悬停反馈承担视觉。 +const OUTLINE_DECORATION = 'border bg-background/80 shadow-md backdrop-blur-sm hover:shadow-lg' + +/** 解析无障碍名称,未传入时回退默认名称。 */ +export function resolveToggleLabel(label?: string): string { + return label ?? DEFAULT_TOGGLE_LABEL +} + +/** 解析按钮形态,未传入时回退默认形态。 */ +export function resolveToggleVariant(variant?: ToggleVariant): ToggleVariant { + return variant ?? DEFAULT_TOGGLE_VARIANT +} + +/** 解析形态专属装饰类,ghost 形态返回 undefined 以交由调用方的 cn 忽略。 */ +export function resolveToggleDecoration(variant: ToggleVariant): string | undefined { + return variant === 'outline' ? OUTLINE_DECORATION : undefined +} diff --git a/packages/components/tsconfig.json b/packages/components/tsconfig.json new file mode 100644 index 0000000..3bfff8a --- /dev/null +++ b/packages/components/tsconfig.json @@ -0,0 +1,18 @@ +{ + "compilerOptions": { + "target": "ESNext", + "module": "ESNext", + "moduleResolution": "Bundler", + "lib": ["ESNext", "DOM", "DOM.Iterable"], + "strict": true, + "noEmit": true, + "skipLibCheck": true, + "isolatedModules": true, + "resolveJsonModule": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true, + "allowImportingTsExtensions": true, + "types": [] + }, + "include": ["src/**/*.ts", "src/**/*.svelte"] +} diff --git a/packages/shared/src/utils/storage.ts b/packages/shared/src/utils/storage.ts index 4f707de..41e18de 100644 --- a/packages/shared/src/utils/storage.ts +++ b/packages/shared/src/utils/storage.ts @@ -1,5 +1,6 @@ // 运行环境检测:SSR 时不存在 window 对象,采用特性检测替代框架环境变量。 -const isBrowser = () => typeof window !== 'undefined' +// 供 storage 内部与跨包的环境判定复用,避免各处重复实现同一检测。 +export const isBrowser = () => typeof window !== 'undefined' type StorageType = { set: (key: string, value: any) => void diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a1d8f98..2925b04 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -245,6 +245,9 @@ importers: '@myblog/auth': specifier: workspace:* version: link:../../packages/auth + '@myblog/components': + specifier: workspace:* + version: link:../../packages/components '@myblog/http': specifier: workspace:* version: link:../../packages/http @@ -303,6 +306,9 @@ importers: '@myblog/auth': specifier: workspace:* version: link:../../packages/auth + '@myblog/components': + specifier: workspace:* + version: link:../../packages/components '@myblog/http': specifier: workspace:* version: link:../../packages/http @@ -424,6 +430,34 @@ importers: specifier: 'catalog:' version: 4.1.11(@types/node@24.13.3)(vite@8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.12)(yaml@2.9.1)) + packages/components: + dependencies: + '@lucide/svelte': + specifier: 'catalog:' + version: 1.34.0(svelte@5.56.10(@typescript-eslint/types@8.68.0)) + '@myblog/shared': + specifier: workspace:* + version: link:../shared + '@myblog/ui': + specifier: workspace:* + version: link:../ui + mode-watcher: + specifier: 'catalog:' + version: 1.1.0(svelte@5.56.10(@typescript-eslint/types@8.68.0)) + devDependencies: + svelte: + specifier: 'catalog:' + version: 5.56.10(@typescript-eslint/types@8.68.0) + svelte-check: + specifier: 'catalog:' + version: 4.7.6(picomatch@4.0.7)(svelte@5.56.10(@typescript-eslint/types@8.68.0))(typescript@6.0.3) + typescript: + specifier: 'catalog:' + version: 6.0.3 + vitest: + specifier: 'catalog:' + version: 4.1.11(@types/node@24.13.3)(vite@8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.12)(yaml@2.9.1)) + packages/http: dependencies: '@myblog/shared': diff --git a/scripts/format-check.ts b/scripts/format-check.ts index 8ad37ee..52ad93f 100644 --- a/scripts/format-check.ts +++ b/scripts/format-check.ts @@ -27,7 +27,8 @@ const PACKAGE_SOURCE_DIRECTORIES = [ 'packages/shared', 'packages/http', 'packages/api', - 'packages/auth' + 'packages/auth', + 'packages/components' ] // paraglide 生成产物目录,该目录由构建过程写出,不纳入格式门禁。 diff --git a/scripts/pre-commit-guard.ts b/scripts/pre-commit-guard.ts index d725234..9ec722a 100644 --- a/scripts/pre-commit-guard.ts +++ b/scripts/pre-commit-guard.ts @@ -25,7 +25,12 @@ const packagesDirectoryPrefix = 'packages' const appsDirectoryPrefix = 'apps' // 纳入 vitest 门禁的工作区包,与根 test:packages 的口径保持一致。 -const gatedWorkspacePackages: string[] = ['packages/api', 'packages/auth', 'packages/http'] +const gatedWorkspacePackages: string[] = [ + 'packages/api', + 'packages/auth', + 'packages/components', + 'packages/http' +] // 纳入 vitest 门禁的应用,与根 test:apps 的口径保持一致。 // 两应用各自持有页面状态模块与渲染管线的单测,提交前必须与 packages 同级把关。 diff --git a/server/cmd/myblog/main.go b/server/cmd/myblog/main.go index fb29ac7..439aa55 100644 --- a/server/cmd/myblog/main.go +++ b/server/cmd/myblog/main.go @@ -58,7 +58,10 @@ func main() { // 按业务域装配依赖并注册路由 deps := newDependencies(cfg, db) metricsRegistry := metrics.New() - routerManager := router.NewRouter(cfg, metricsRegistry.Middleware()) + routerManager, err := router.NewRouter(cfg, metricsRegistry.Middleware()) + if err != nil { + exitWithError("路由初始化失败", err) + } routerManager.SetupRoutes(deps) // 指标监听独立于业务端口,未启用时返回空句柄。 diff --git a/server/configs/config.example.yaml b/server/configs/config.example.yaml index a80eea1..81bcc8f 100644 --- a/server/configs/config.example.yaml +++ b/server/configs/config.example.yaml @@ -50,6 +50,14 @@ token: # API安全配置 security: + # 反向代理信任链:仅列表内的来源所携带的 X-Forwarded-For 才参与客户端 IP 解析。 + # 默认只信任本机回环,同机 nginx 反代可直接使用;容器编排经 + # MYBLOG_SECURITY_TRUSTED_PROXIES 以逗号分隔注入(例如 172.16.0.0/12)。 + # 置空表示服务前方没有代理,客户端 IP 一律取连接来源地址。 + trusted_proxies: + - "127.0.0.1/32" + - "::1/128" + # 频率限制配置 rate_limit: enabled: true diff --git a/server/configs/config.yaml b/server/configs/config.yaml index ec72bc6..022ca14 100644 --- a/server/configs/config.yaml +++ b/server/configs/config.yaml @@ -43,6 +43,14 @@ token: # API安全配置 security: + # 反向代理信任链:仅列表内的来源所携带的 X-Forwarded-For 才参与客户端 IP 解析。 + # 默认只信任本机回环,同机 nginx 反代可直接使用;容器编排经 + # MYBLOG_SECURITY_TRUSTED_PROXIES 以逗号分隔注入(例如 172.16.0.0/12)。 + # 置空表示服务前方没有代理,客户端 IP 一律取连接来源地址。 + trusted_proxies: + - "127.0.0.1/32" + - "::1/128" + # 频率限制配置 rate_limit: enabled: true diff --git a/server/docs/api/session-api.md b/server/docs/api/session-api.md index db975d5..9d82a67 100644 --- a/server/docs/api/session-api.md +++ b/server/docs/api/session-api.md @@ -105,5 +105,5 @@ curl -X POST http://localhost:3000/api/auth/session \ ## 已知限制 -- 令牌表为**进程内存**结构,服务重启或发布导致全体用户登出;多副本部署前必须完成令牌表持久化(见 [`docs/architecture-rules.md`](../../../docs/architecture-rules.md) 第 7 节)。 +- 令牌表为**进程内存**结构,服务重启或发布导致全体用户登出;本项目为单实例终态且不扩容,故不做持久化,改变该决定时须先完成迁移(见 [`docs/architecture-rules.md`](../../../docs/architecture-rules.md) §7.2)。 - 会话 Cookie 由同源标签页共享,令牌旋转不产生跨标签页竞争。 diff --git a/server/internal/config/README.md b/server/internal/config/README.md index 6b4e744..522cadf 100644 --- a/server/internal/config/README.md +++ b/server/internal/config/README.md @@ -6,7 +6,7 @@ - `Load(configPath)` 经 `sync.Once` 单例加载,进程内只生效一次;`Get()` 在未初始化时 panic;`GetDSN()`、`GetServerAddress()` 提供派生值。 - 代码默认值集中在 `setDefaults()`,YAML 缺项时按默认值生效。 -- 标量配置项可经 `MYBLOG_
_` 环境变量覆盖,例如 `server.port` 对应 `MYBLOG_SERVER_PORT`;列表与映射无法经单个变量无损表达,保持 YAML 原值。 +- 标量配置项可经 `MYBLOG_
_` 环境变量覆盖,例如 `server.port` 对应 `MYBLOG_SERVER_PORT`;列表与映射无法经单个变量无损表达,保持 YAML 原值。唯一例外是 `security.trusted_proxies`,其专用通道 `MYBLOG_SECURITY_TRUSTED_PROXIES` 按逗号分隔解析,取值为空串表示不信任任何代理。 ## 校验规则 @@ -17,11 +17,13 @@ - `token.access_expire` 或 `token.refresh_expire` 不为正数。 - `rbac.role_hierarchy` 或 `rbac.role_permissions` 缺少 superadmin、admin、editor、user 任一类角色的定义。 - `i18n.supported_languages` 为空,或 `i18n.default_language` 不在该列表内。 +- `security.trusted_proxies` 含空项、非法 IP 或 CIDR,或出现 `0.0.0.0/0` 与 `::/0` 这类覆盖全部地址的取值。 ## 约定 - 令牌为服务端签发的不透明随机串,不存在签名密钥与签发者配置;`token.cookie_secure` 控制会话 Cookie 是否仅经 HTTPS 传输,生产环境必须开启。 - 权限映射的生产环境唯一权威为 `rbac` 节,服务层经 `service.LoadRBACConfig` 读取,见 `cmd/myblog/deps.go`。 - 各子配置节的字段含义以 `configs/config.yaml` 注释为准。 +- `security.trusted_proxies` 默认只信任本机回环,`internal/router` 在构造引擎时据此调用 `SetTrustedProxies`;仅列表内来源携带的 `X-Forwarded-For` 参与 `ClientIP()` 解析,容器编排须经环境变量注入容器网段,漏配时客户端 IP 会退化为网关地址。 相关约束见 `docs/development.md`「核心模块」。 diff --git a/server/internal/config/config.go b/server/internal/config/config.go index badf505..94dd57a 100644 --- a/server/internal/config/config.go +++ b/server/internal/config/config.go @@ -109,6 +109,8 @@ type SecurityConfig struct { InputValidation InputValidationConfig `mapstructure:"input_validation"` AdminSecurity AdminSecurityConfig `mapstructure:"admin_security"` LoginLockout LoginLockoutConfig `mapstructure:"login_lockout"` + // TrustedProxies 受信代理来源列表,仅列表内的来源所携带的转发头参与客户端 IP 解析。 + TrustedProxies []string `mapstructure:"trusted_proxies"` } // LoginLockoutConfig 登录锁定配置,连续失败达到阈值后锁定账户一段时间。 @@ -160,6 +162,14 @@ var ( // envKeyPrefix 环境变量统一前缀,完整变量名由该前缀与配置键转换拼接得到。 const envKeyPrefix = "MYBLOG" +// trustedProxiesEnvKey 代理信任链专用环境变量名。 +// 通用覆盖只处理标量,列表项无法经单个环境变量无损表达,故为该键单独提供逗号分隔的注入通道。 +const trustedProxiesEnvKey = envKeyPrefix + "_SECURITY_TRUSTED_PROXIES" + +// defaultTrustedProxies 未配置时的受信来源,只覆盖本机回环。 +// 默认收敛而非放开,避免漏配时退化为信任任何来源携带的转发头。 +var defaultTrustedProxies = []string{"127.0.0.1/32", "::1/128"} + // Load 加载配置文件 func Load(configPath string) (*Config, error) { var err error @@ -179,6 +189,9 @@ func Load(configPath string) (*Config, error) { // 环境变量覆盖标量配置,敏感项在生产环境经环境注入,不再依赖 YAML 明文。 applyEnvOverrides(viper.GetViper()) + // 代理信任链为列表,通用覆盖会跳过容器类型,此处按逗号分隔单独注入。 + applyTrustedProxiesOverride(viper.GetViper()) + // 解析配置到结构体 config = &Config{} if err = viper.Unmarshal(config); err != nil { @@ -272,6 +285,10 @@ func setDefaults() { viper.SetDefault("security.login_lockout.max_failed_attempts", 5) viper.SetDefault("security.login_lockout.lock_minutes", 15) + // 代理信任链默认只信任本机回环,同机进程反代开箱可用; + // 容器编排另经 MYBLOG_SECURITY_TRUSTED_PROXIES 注入容器网络来源。 + viper.SetDefault("security.trusted_proxies", defaultTrustedProxies) + // CORS 默认拒绝所有跨域,方法表遵循 POST-Only 规范仅保留 POST 与预检 OPTIONS, // 需要跨域访问的部署在 config.yaml 白名单中补充具体 Origin。 viper.SetDefault("cors.allowed_origins", []string{}) @@ -314,10 +331,31 @@ func envVariableName(key string) string { return envKeyPrefix + "_" + strings.ReplaceAll(upperKey, ".", "_") } +// applyTrustedProxiesOverride 以逗号分隔的列表覆盖代理信任链配置。 +// 变量存在但取值为空串时解析为空列表,表示服务前方没有代理,客户端 IP 一律取连接来源地址。 +func applyTrustedProxiesOverride(v *viper.Viper) { + raw, ok := os.LookupEnv(trustedProxiesEnvKey) + if !ok { + return + } + v.Set("security.trusted_proxies", splitTrustedProxies(raw)) +} + +// splitTrustedProxies 按逗号切分代理信任链取值,丢弃其中的空白项。 +func splitTrustedProxies(raw string) []string { + entries := make([]string, 0, strings.Count(raw, ",")+1) + for _, item := range strings.Split(raw, ",") { + if entry := strings.TrimSpace(item); entry != "" { + entries = append(entries, entry) + } + } + return entries +} + // isScalarConfigValue 判断配置值是否为可经环境变量表达的标量,列表与映射等容器类型返回 false。 func isScalarConfigValue(value any) bool { switch value.(type) { - case map[string]any, map[any]any, []any: + case map[string]any, map[any]any, []any, []string: return false default: return true @@ -388,5 +426,33 @@ func validateConfig(cfg *Config) error { } } + // 代理信任链校验:非法来源会让引擎构造失败,而覆盖全部地址的取值等同于关闭信任链, + // 两者都必须在启动期拦截,不留到运行期才暴露。 + for _, entry := range cfg.Security.TrustedProxies { + if err := validateTrustedProxy(entry); err != nil { + return err + } + } + return nil } + +// validateTrustedProxy 校验单个代理信任项,接受单个 IP 或 CIDR,拒绝覆盖全部地址的取值。 +func validateTrustedProxy(entry string) error { + if entry == "" { + return fmt.Errorf("代理信任项不能为空") + } + + if _, network, err := net.ParseCIDR(entry); err == nil { + if ones, _ := network.Mask.Size(); ones == 0 { + return fmt.Errorf("代理信任项 %q 覆盖全部地址,等同于关闭信任链校验", entry) + } + return nil + } + + if net.ParseIP(entry) != nil { + return nil + } + + return fmt.Errorf("无效的代理信任项 %q:需为 IP 或 CIDR", entry) +} diff --git a/server/internal/config/config_test.go b/server/internal/config/config_test.go index b3a0fd6..c815dfb 100644 --- a/server/internal/config/config_test.go +++ b/server/internal/config/config_test.go @@ -1,6 +1,7 @@ package config import ( + "os" "testing" "github.com/spf13/viper" @@ -189,4 +190,133 @@ func TestLoadParsesConfigSections(t *testing.T) { if viper.InConfig("jwt.access_expire") || viper.InConfig("jwt.refresh_expire") { t.Error("config.yaml 不应再出现 jwt 节") } + // 代理信任链默认收敛:声明值缺失会被代码默认值兜住,但两者必须一致且仅覆盖回环。 + if len(cfg.Security.TrustedProxies) != 2 { + t.Errorf("security.trusted_proxies = %v, 期望声明两个回环信任项", cfg.Security.TrustedProxies) + } +} + +// TestValidateConfigRejectsInvalidTrustedProxy 验证非法代理信任项即拒绝启动。 +func TestValidateConfigRejectsInvalidTrustedProxy(t *testing.T) { + cfg := validTestConfig() + cfg.Security.TrustedProxies = []string{"127.0.0.1/32", "not-an-address"} + + if err := validateConfig(cfg); err == nil { + t.Error("非法代理信任项应返回错误") + } +} + +// TestValidateConfigRejectsTrustAllTrustedProxy 验证覆盖全部地址的信任项即拒绝启动。 +// 该取值等同于关闭信任链校验,与默认收敛的方向相反,必须拦截。 +func TestValidateConfigRejectsTrustAllTrustedProxy(t *testing.T) { + for _, entry := range []string{"0.0.0.0/0", "::/0"} { + cfg := validTestConfig() + cfg.Security.TrustedProxies = []string{entry} + + if err := validateConfig(cfg); err == nil { + t.Errorf("信任项 %q 覆盖全部地址,应返回错误", entry) + } + } +} + +// TestValidateConfigAcceptsTrustedProxyEntries 验证单 IP 与网段两种写法均通过校验。 +func TestValidateConfigAcceptsTrustedProxyEntries(t *testing.T) { + cfg := validTestConfig() + cfg.Security.TrustedProxies = []string{"127.0.0.1", "::1", "172.16.0.0/12"} + + if err := validateConfig(cfg); err != nil { + t.Errorf("合法代理信任项不应返回错误: %v", err) + } +} + +// TestValidateConfigAcceptsEmptyTrustedProxies 验证空列表表示服务前方没有代理,属合法配置。 +func TestValidateConfigAcceptsEmptyTrustedProxies(t *testing.T) { + cfg := validTestConfig() + cfg.Security.TrustedProxies = nil + + if err := validateConfig(cfg); err != nil { + t.Errorf("未配置代理信任项不应返回错误: %v", err) + } +} + +// TestApplyTrustedProxiesOverrideSplitsList 验证列表值可经专用环境变量按逗号注入。 +func TestApplyTrustedProxiesOverrideSplitsList(t *testing.T) { + t.Setenv(trustedProxiesEnvKey, "172.16.0.0/12, 127.0.0.1/32") + + v := viper.New() + v.Set("security.trusted_proxies", []string{"127.0.0.1/32"}) + + applyTrustedProxiesOverride(v) + + entries := v.GetStringSlice("security.trusted_proxies") + if len(entries) != 2 || entries[0] != "172.16.0.0/12" || entries[1] != "127.0.0.1/32" { + t.Errorf("trusted_proxies = %v, 期望解析出两个信任项且按声明顺序排列", entries) + } +} + +// TestApplyTrustedProxiesOverrideEmptyMeansNoProxy 验证变量取值为空串时解析为空列表。 +func TestApplyTrustedProxiesOverrideEmptyMeansNoProxy(t *testing.T) { + t.Setenv(trustedProxiesEnvKey, "") + + v := viper.New() + v.Set("security.trusted_proxies", []string{"127.0.0.1/32"}) + + applyTrustedProxiesOverride(v) + + if entries := v.GetStringSlice("security.trusted_proxies"); len(entries) != 0 { + t.Errorf("trusted_proxies = %v, 期望空列表表示不信任任何代理", entries) + } +} + +// TestApplyTrustedProxiesOverrideKeepsYAMLWhenEnvMissing 验证未注入环境变量时保持配置文件取值。 +func TestApplyTrustedProxiesOverrideKeepsYAMLWhenEnvMissing(t *testing.T) { + if _, ok := os.LookupEnv(trustedProxiesEnvKey); ok { + t.Skipf("环境已存在 %s,跳过未注入分支", trustedProxiesEnvKey) + } + + v := viper.New() + v.Set("security.trusted_proxies", []string{"127.0.0.1/32"}) + + applyTrustedProxiesOverride(v) + + entries := v.GetStringSlice("security.trusted_proxies") + if len(entries) != 1 || entries[0] != "127.0.0.1/32" { + t.Errorf("trusted_proxies = %v, 期望保持配置文件取值", entries) + } +} + +// TestApplyEnvOverridesSkipsStringSlice 验证字符串列表配置项不被通用覆盖改写, +// 列表类配置只能经各自的专用通道注入。 +func TestApplyEnvOverridesSkipsStringSlice(t *testing.T) { + t.Setenv("MYBLOG_I18N_SUPPORTED_LANGUAGES", "zh,en,fr") + + v := viper.New() + v.Set("i18n.supported_languages", []string{"zh", "en"}) + + applyEnvOverrides(v) + + if entries := v.GetStringSlice("i18n.supported_languages"); len(entries) != 2 { + t.Errorf("supported_languages = %v, 期望保持配置文件原值", entries) + } +} + +// TestTrustedProxiesEnvOverrideReachesConfigStruct 验证环境注入的信任链取值贯通到配置结构体, +// 该路径是容器编排生效的唯一通道。 +func TestTrustedProxiesEnvOverrideReachesConfigStruct(t *testing.T) { + t.Setenv(trustedProxiesEnvKey, "172.16.0.0/12") + + // 复刻 Load 的取值顺序:先落默认值,再应用专用环境通道,最后解析到结构体。 + v := viper.New() + v.SetDefault("security.trusted_proxies", defaultTrustedProxies) + applyTrustedProxiesOverride(v) + + var cfg Config + if err := v.Unmarshal(&cfg); err != nil { + t.Fatalf("解析配置失败: %v", err) + } + + entries := cfg.Security.TrustedProxies + if len(entries) != 1 || entries[0] != "172.16.0.0/12" { + t.Errorf("Security.TrustedProxies = %v, 期望解析出环境注入的单个网段", entries) + } } diff --git a/server/internal/middleware/README.md b/server/internal/middleware/README.md index c0e712f..2d76a6f 100644 --- a/server/internal/middleware/README.md +++ b/server/internal/middleware/README.md @@ -10,7 +10,7 @@ HTTP 横切层。认证与权限中间件只依赖 `IdentityProvider` 抽象, | `cors.go` | `CORSWithConfig` | Origin 白名单精确匹配,白名单外与未携带 Origin 的请求不回显任何 CORS 头,`OPTIONS` 统一 204,所有响应带 `Vary: Origin`;规则来自 `cors` 节 | | `security.go` | `SecurityMiddleware`、`DefaultSecurityConfig`、`SecurityMiddlewareFromConfig`、`AdminSecurityMiddlewareFromConfig`、`IPWhitelistMiddleware` | IP 与用户两级限流、安全响应头、请求体上限(普通接口 10MB、管理员接口 5MB)、User-Agent 子串黑名单、恶意模式检测(`getDefaultBlockedPatterns`,模式经词首边界锚定;JSON 体按字段路径扫描,正文 `content` 与 `i18n.*.content` 豁免,见 `richContentJSONPaths`) | | `auth.go` | `Auth`、`OptionalAuth`、`AdminAuth`、`RequireRole` | 访问令牌校验;令牌经 `Authorization: Bearer` 与 `mb_access_token` Cookie 双轨解析,仅向上下文注入 `userID` | -| `identity.go` | `IdentityProvider`、`NewIdentityProvider` | 身份解析抽象与唯一实现,依次校验令牌、用户状态与角色有效性,失败时已写入响应并中止请求链 | +| `identity.go` | `IdentityProvider`、`NewIdentityProvider` | 身份解析抽象与唯一实现,依次校验令牌、用户状态与角色有效性,失败时已写入响应并中止请求链;实现所消费的用户读取能力由本包声明窄接口 `userLookup`,仓储实现经组合根注入,故本包不依赖 `internal/repository` | | `rbac.go` | `RequirePermission`、`RequireAllPermissions`、`RequireRoleLevel`、`RequireSuperAdmin`、`RequireAdminOrAbove`、`RequireEditorOrAbove`、`RequireOwnershipOrAdmin`、`CanManageUserRole`、`GetCurrentUser`、`GetCurrentUserID`、`GetCurrentUserRole` | RBAC 鉴权与上下文读取,权限判定全部委托注入的 `RBACService` | | `ratelimit.go` | `RateLimit`、`RateLimitPerUser`、`RateLimiter`、`NewRateLimiter` | 进程内计数限流器,安全中间件复用同一实现;过期记录随新客户端加入惰性清扫 | | `language.go` | `LanguageMiddlewareFromConfig` | 解析 `Accept-Language` 写入请求上下文,白名单外回退缺省语言;只解析不中断请求 | @@ -20,5 +20,6 @@ HTTP 横切层。认证与权限中间件只依赖 `IdentityProvider` 抽象, - 全局中间件顺序见 `internal/router/router.go`:RequestID、指标记录、Logger、Recovery、CORS、Security、Language;管理员分组额外挂 `AdminSecurityMiddlewareFromConfig`。 - 日志输出为 JSON 行,初始化与请求标识读取见 `internal/logger`;请求级记录统一经 `logger.FromGin(c)` 取日志器,字段键取自 `logger.Field*` 常量。 - 权限清单唯一权威为 `configs/config.yaml` 的 `rbac.role_permissions`,本文件不重复罗列。 -- 限流计数与令牌表均为进程内存结构,单实例部署前提下的取舍与扩容前置改造见 `docs/architecture-rules.md` §7。 +- 限流计数与令牌表均为进程内存结构,属单实例终态下的已接受取舍,变更前提见 `docs/architecture-rules.md` §7.2。 +- `ClientIP()` 的取值受 `security.trusted_proxies` 约束,仅受信来源携带的 `X-Forwarded-For` 参与解析,配置与默认值见 `internal/config/README.md`;漏配容器网段会让 IP 限流、审计落库与访客去重全部归并到网关一个键上。 - 实例化纪律(依赖由组合根注入)见 `docs/architecture-rules.md` §5.2。 diff --git a/server/internal/middleware/identity.go b/server/internal/middleware/identity.go index ad347c5..da320c9 100644 --- a/server/internal/middleware/identity.go +++ b/server/internal/middleware/identity.go @@ -6,7 +6,6 @@ import ( "MyBlog/internal/domain" "MyBlog/internal/model" - "MyBlog/internal/repository" "MyBlog/internal/service" "MyBlog/pkg/response" @@ -20,14 +19,20 @@ type IdentityProvider interface { Resolve(c *gin.Context) (*domain.User, error) } +// userLookup 身份解析所需的用户读取能力,在消费方声明为窄接口,使本包不依赖仓储包的具体类型。 +// 仓储实现由组合根注入,结构化满足该接口,接口随存储层方法演进而按需扩列。 +type userLookup interface { + GetByID(id uint) (*domain.User, error) +} + // tokenIdentityProvider 基于令牌表与用户仓储的身份解析实现。 type tokenIdentityProvider struct { tokenService service.TokenServiceInterface - userRepo repository.UserRepository + userRepo userLookup } // NewIdentityProvider 创建身份解析器,依赖由组合根注入。 -func NewIdentityProvider(tokenService service.TokenServiceInterface, userRepo repository.UserRepository) IdentityProvider { +func NewIdentityProvider(tokenService service.TokenServiceInterface, userRepo userLookup) IdentityProvider { return &tokenIdentityProvider{ tokenService: tokenService, userRepo: userRepo, diff --git a/server/internal/repository/README.md b/server/internal/repository/README.md index 75d3421..d89d24a 100644 --- a/server/internal/repository/README.md +++ b/server/internal/repository/README.md @@ -10,6 +10,6 @@ - 删除使用 GORM 软删除;唯一性与索引约束声明在实体的 `gorm` tag 上(用户名、邮箱为唯一索引,`domain.User` 见 `internal/domain/user.go`)。 - 多段写库在同一事务内提交,沿用既有的 `xxxTx` 事务方法先例。 -方法签名(含分页与过滤参数,如用户仓库的 `List(offset, limit int, keyword string)`)以各 `repository/*.go` 的接口声明为准。 +方法签名(含分页与过滤参数,如用户仓库的 `List(offset, limit int, keyword string)`)以各 `repository/*.go` 的接口声明为准。查询参数与结果结构(如 `ArticleListParams`、`ArticleArchiveGroup`)随接口声明在本包,属接口签名的组成部分,不视作上文禁止的实体或 DTO 定义。 表结构设计的硬性约定见 `docs/database-architecture.md`「设计原则」,本包只在实体 tag 层面声明索引与删除策略。 diff --git a/server/internal/router/router.go b/server/internal/router/router.go index c914e70..734cdb2 100644 --- a/server/internal/router/router.go +++ b/server/internal/router/router.go @@ -1,6 +1,7 @@ package router import ( + "fmt" "net/http" "MyBlog/internal/config" @@ -20,9 +21,16 @@ type Router struct { // NewRouter 创建新的路由管理器。 // requestMetrics 为指标记录中间件,由组合根注入,路由层不依赖具体指标实现。 -func NewRouter(cfg *config.Config, requestMetrics gin.HandlerFunc) *Router { +// 代理信任链取值非法时返回错误,由组合根在启动期终止进程。 +func NewRouter(cfg *config.Config, requestMetrics gin.HandlerFunc) (*Router, error) { engine := gin.New() + // 收敛代理信任链:仅受信来源携带的转发头参与客户端 IP 解析。 + // 缺此配置时引擎默认信任全部来源,客户端可伪造 X-Forwarded-For 绕过 IP 限流并污染审计记录。 + if err := engine.SetTrustedProxies(cfg.Security.TrustedProxies); err != nil { + return nil, fmt.Errorf("设置代理信任链失败: %w", err) + } + // 设置全局中间件。 // 请求标识最先写入,访问日志与指标记录均以它为关联字段。 engine.Use(middleware.RequestID()) // 请求ID中间件 @@ -48,7 +56,7 @@ func NewRouter(cfg *config.Config, requestMetrics gin.HandlerFunc) *Router { return &Router{ engine: engine, cfg: cfg, - } + }, nil } // GetEngine 获取 Gin 引擎实例 diff --git a/server/internal/router/router_trusted_proxy_test.go b/server/internal/router/router_trusted_proxy_test.go new file mode 100644 index 0000000..31bd00b --- /dev/null +++ b/server/internal/router/router_trusted_proxy_test.go @@ -0,0 +1,108 @@ +package router + +import ( + "net/http" + "net/http/httptest" + "testing" + + "MyBlog/internal/config" + + "github.com/gin-gonic/gin" +) + +// clientIPProbe 以指标中间件位置作为探针捕获引擎解析出的客户端 IP。 +// 引擎已挂载静态服务的通配路由,追加探针路由会与之冲突,故复用中间件注入点。 +func clientIPProbe(t *testing.T, trustedProxies []string) (*gin.Engine, *string) { + t.Helper() + + gin.SetMode(gin.TestMode) + captured := new(string) + cfg := &config.Config{ + Security: config.SecurityConfig{TrustedProxies: trustedProxies}, + Media: config.MediaConfig{BaseURL: "/uploads", UploadDir: t.TempDir()}, + } + + manager, err := NewRouter(cfg, func(c *gin.Context) { + *captured = c.ClientIP() + c.Next() + }) + if err != nil { + t.Fatalf("构建路由失败: %v", err) + } + + return manager.GetEngine(), captured +} + +// performProbeRequest 发送一次指定来源地址与转发头的探针请求。 +func performProbeRequest(t *testing.T, engine *gin.Engine, remoteAddr, forwardedFor string) { + t.Helper() + + req := httptest.NewRequest(http.MethodGet, "/probe-client-ip", nil) + req.RemoteAddr = remoteAddr + if forwardedFor != "" { + req.Header.Set("X-Forwarded-For", forwardedFor) + } + + engine.ServeHTTP(httptest.NewRecorder(), req) +} + +// TestClientIPIgnoresForgedHeaderFromUntrustedPeer 验证非受信来源携带的转发头不被采信, +// 客户端 IP 取连接来源地址。 +func TestClientIPIgnoresForgedHeaderFromUntrustedPeer(t *testing.T) { + engine, captured := clientIPProbe(t, []string{"127.0.0.1/32"}) + + performProbeRequest(t, engine, "203.0.113.9:4321", "1.2.3.4") + + if *captured != "203.0.113.9" { + t.Errorf("ClientIP() = %q, 期望取连接来源地址 203.0.113.9", *captured) + } +} + +// TestClientIPUsesRightmostUntrustedFromTrustedProxy 验证经受信代理转发时取最右侧非受信地址, +// 客户端自带的伪造值位于最左,不参与结果。 +func TestClientIPUsesRightmostUntrustedFromTrustedProxy(t *testing.T) { + engine, captured := clientIPProbe(t, []string{"127.0.0.1/32"}) + + performProbeRequest(t, engine, "127.0.0.1:5555", "1.2.3.4, 203.0.113.9") + + if *captured != "203.0.113.9" { + t.Errorf("ClientIP() = %q, 期望取最右侧非受信地址 203.0.113.9", *captured) + } +} + +// TestClientIPFollowsTrustedProxySingleValue 验证受信代理转发的单值转发头被采信。 +func TestClientIPFollowsTrustedProxySingleValue(t *testing.T) { + engine, captured := clientIPProbe(t, []string{"127.0.0.1/32"}) + + performProbeRequest(t, engine, "127.0.0.1:5555", "203.0.113.9") + + if *captured != "203.0.113.9" { + t.Errorf("ClientIP() = %q, 期望采信受信代理转发的 203.0.113.9", *captured) + } +} + +// TestClientIPIgnoresForwardedHeaderWhenNoProxyTrusted 验证信任列表为空时一律取连接来源地址, +// 即使转发头伪造成受信网段内的地址也不生效。 +func TestClientIPIgnoresForwardedHeaderWhenNoProxyTrusted(t *testing.T) { + engine, captured := clientIPProbe(t, nil) + + performProbeRequest(t, engine, "203.0.113.9:4321", "127.0.0.1, 10.0.0.1") + + if *captured != "203.0.113.9" { + t.Errorf("ClientIP() = %q, 期望取连接来源地址 203.0.113.9", *captured) + } +} + +// TestNewRouterRejectsInvalidTrustedProxy 验证非法信任项在引擎构造阶段即报错, +// 该分支是配置校验之外的第二道拦截。 +func TestNewRouterRejectsInvalidTrustedProxy(t *testing.T) { + gin.SetMode(gin.TestMode) + cfg := &config.Config{ + Security: config.SecurityConfig{TrustedProxies: []string{"not-an-address"}}, + Media: config.MediaConfig{BaseURL: "/uploads", UploadDir: t.TempDir()}, + } + + if _, err := NewRouter(cfg, func(c *gin.Context) { c.Next() }); err == nil { + t.Error("非法代理信任项应返回错误") + } +}