# icewall **Repository Path**: lytofb111/icewall ## Basic Information - **Project Name**: icewall - **Description**: 私有项目，面试展示用 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: trellis - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-29 - **Last Updated**: 2026-05-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 项目文档入口 1. 这个项目有哪些模块 2. 每个模块从哪看详细说明 3. 每个模块怎么快速启动 4. 测试入口和协议边界在哪里 详细说明一律下沉到 `docs/`。 ## 文档树 ```text README.md └── docs/ ├── system-architecture.md # 系统总架构、主链路、模块关系 ├── deployment-topology.md # 单节点开发与多节点目标拓扑 ├── browser-auth-state-contracts.md # Edge 与 auth-service 浏览器状态边界 ├── secrets-key-distribution.md # secrets source 与密钥轮换契约 ├── icewall-icp.md # 主代理链：OpenResty Edge + Go Agent ├── auth-service.md # OAuth / OIDC / MFA 服务边界 ├── icewall-shared.md # Python 共享加载器与 HTTP helper ├── protocol-demos.md # saml / idp / oidc / wsfed / iwa 协议模块、适配器与夹具 ├── engineering-workflow.md # skills / runtime 工件 / 文档工件边界 ├── testing.md # 统一测试入口与回归说明 ├── kerberos-iwa.md # Kerberos / IWA 本地运行手册 ├── wsfed-entra.md # WS-Federation Entra 边界与运行手册 ├── saml-local-demo.md # 本地 SAML 流程与运行手册 ├── index.md # docs 内部索引 └── archive/ # 历史材料（包含旧 requirements.md） ``` ## 模块总览 | 模块 | 作用 | 详细文档 | | --- | --- | --- | | `src/icewall-icp/` | 主运行时：OpenResty Edge、Go Agent、本地 mock upstream | [docs/icewall-icp.md](./docs/icewall-icp.md) | | `src/auth-service/` | OAuth / OIDC、token introspection、MFA、WebAuthn、管理面 | [docs/auth-service.md](./docs/auth-service.md) | | `src/icewall_shared/` | Python 服务共享加载器和 HTTP helper | [docs/icewall-shared.md](./docs/icewall-shared.md) | | `src/saml/` `src/idp/` `src/oidc/` `src/wsfed/` `src/iwa/` | 协议模块、联邦适配器、身份源夹具和 E2E 支撑服务 | [docs/protocol-demos.md](./docs/protocol-demos.md) | | `tests/e2e/` | 容器栈、浏览器回归、主机侧协议回归 | [docs/testing.md](./docs/testing.md) | | `skills/` | 仓库内 orchestrator / worker / gate 工具链 | [docs/engineering-workflow.md](./docs/engineering-workflow.md) | ## Quick Start ### 1. 主代理链：`src/icewall-icp/` - 先启动本地上游： - `python3 src/icewall-icp/backend_server.py` - 再启动 Go Agent： - `cd src/icewall-icp/agent && go build ./cmd/forwarder && ./forwarder -config ./config/agent.yaml` - 最后加载 OpenResty Edge： - `src/icewall-icp/edge/conf.d/nginx.conf` - 细节看： - [docs/icewall-icp.md](./docs/icewall-icp.md) - [docs/system-architecture.md](./docs/system-architecture.md) - [docs/deployment-topology.md](./docs/deployment-topology.md) ### 2. 认证服务：`src/auth-service/` - 默认运行入口： - `bash deploy/scripts/up.sh` - 如果你只想单独调 `auth-service`，先准备可访问的 PostgreSQL，再显式提供 `AUTH_SERVICE_DB_URL`、`AUTH_SERVICE_SESSION_SECRET`、`AUTH_SERVICE_JWKS_PATH` 和 `AUTH_SERVICE_WEBAUTHN_ORIGINS` 后启动。 - 不再支持“没数据库直接跑起来再说”这种假本地模式。 - 细节看： - [docs/auth-service.md](./docs/auth-service.md) - [docs/deployment-topology.md](./docs/deployment-topology.md) ### 3. 协议模块与身份夹具：`src/saml/` `src/idp/` `src/oidc/` `src/wsfed/` `src/iwa/` - 统一从仓库根启动，不要再在子目录里乱跑 `python app.py`： - `python3 scripts/run_python_entry.py src/saml/app.py --host 127.0.0.1 --port 19000` - `python3 scripts/run_python_entry.py src/idp/app.py --host 127.0.0.1 --port 19010` - `python3 scripts/run_python_entry.py src/oidc/app.py --host 127.0.0.1 --port 19110` - `python3 scripts/run_python_entry.py src/wsfed/app.py --host 127.0.0.1 --port 19400` - `python3 scripts/run_python_entry.py src/iwa/app.py --host 127.0.0.1 --port 19500` - 这些端口只是本地示例，不是协议契约。 - 细节看： - [docs/protocol-demos.md](./docs/protocol-demos.md) - [docs/saml-local-demo.md](./docs/saml-local-demo.md) - [docs/wsfed-entra.md](./docs/wsfed-entra.md) - [docs/kerberos-iwa.md](./docs/kerberos-iwa.md) ### 4. 共享库：`src/icewall_shared/` - 这是共享 Python 库，没有独立进程入口。 - 先看： - [docs/icewall-shared.md](./docs/icewall-shared.md) ### 5. 工程流程：`skills/` - 需求转 durable 工件： - `skills/spec-to-orchestrator` - 编排与执行： - `skills/orchestrate-parallel-codex` - worker 启动： - `skills/run-codex-worker` - 评审与过闸： - `skills/reviewing-and-gating-commits` - 细节看： - [docs/engineering-workflow.md](./docs/engineering-workflow.md) ## 测试入口 ### 仓库级入口 - `make test` - `make test-e2e` - `make test-python` `make test-python` 不是轻量的模块单测入口；它还会带上顶层契约和 deploy smoke。只想验证主实现时，优先用下面的关键模块入口。 ### 关键模块入口 - `pytest src/auth-service/tests -q` - `pytest src/saml/tests src/idp/tests src/oidc/tests src/wsfed/tests src/iwa/tests -q` - `pytest tests/e2e -q` 更完整的测试分层和命令说明看： - [docs/testing.md](./docs/testing.md) ## 协议说明 ### 主链路协议 - `ICP` - Edge 到 Agent 的受控代理链路，带 `mTLS + Ed25519` 签名 - 细节看 [docs/icewall-icp.md](./docs/icewall-icp.md) - `OAuth 2.0 / OpenID Connect 1.0` - 服务端能力由 `src/auth-service/` 提供 - 细节看 [docs/auth-service.md](./docs/auth-service.md) - `SAML 2.0` - 本地 `SAML` 路径、联邦登录和测试夹具见 [docs/saml-local-demo.md](./docs/saml-local-demo.md) 与 [docs/protocol-demos.md](./docs/protocol-demos.md) - `WS-Federation / WS-Trust` - 本地 `local` 模式与 `Entra` 边界见 [docs/wsfed-entra.md](./docs/wsfed-entra.md) - `Kerberos / IWA` - 当前只提供 local `MIT KDC-backed` baseline，覆盖 `ICEWALL.TEST` 与 `PARTNER.TEST` 的 `cross-realm trust` - 这不是生产 AD rollout 指南 - 浏览器侧还保留 `browser auto-domain-login` 基线 - 入口文档是 [docs/kerberos-iwa.md](./docs/kerberos-iwa.md) ### 协议专项入口 - `WS-Federation Entra` - 预检查：`make test-wsfed-entra-precheck` - 预检查并 `fetch metadata`：`make test-wsfed-entra-precheck-fetch-metadata` - live smoke：`make test-wsfed-entra-live` - live browser smoke：`make test-wsfed-entra-live-browser` - 依赖：`src/wsfed/.env.entra` - 浏览器包装脚本：`tests/e2e/run_playwright_wsfed_entra_live_browser_qa.sh` - 机器可读工件： - `precheck.json` - `smoke.json` - `browser.json` - `context.json` - `timing.json` - `mode.json` - 细节看 [docs/wsfed-entra.md](./docs/wsfed-entra.md) - `Kerberos / IWA` - 主机侧回归：`pytest tests/e2e/test_iwa_flow.py -q` - cross-realm 回归：`pytest tests/e2e/test_iwa_cross_realm_flow.py -q` - 浏览器 QA：`tests/e2e/run_playwright_iwa_browser_qa.sh` - 细节看 [docs/kerberos-iwa.md](./docs/kerberos-iwa.md) ## 从哪里开始读 如果你只想快速理解当前系统，按这个顺序读： 1. [docs/system-architecture.md](./docs/system-architecture.md) 2. [docs/deployment-topology.md](./docs/deployment-topology.md) 3. [docs/browser-auth-state-contracts.md](./docs/browser-auth-state-contracts.md) 4. [docs/secrets-key-distribution.md](./docs/secrets-key-distribution.md) 5. [docs/icewall-icp.md](./docs/icewall-icp.md) 6. [docs/auth-service.md](./docs/auth-service.md) 7. [docs/protocol-demos.md](./docs/protocol-demos.md) 8. [docs/testing.md](./docs/testing.md) 9. [docs/archive/requirements.md](./docs/archive/requirements.md)