feat: configure network access policies through environment
This commit is contained in:
陈煜 committed
1 parent
91365ee315
commit
265f28e16d
17 files changed
+456
-58
No files matched your search
+12
-3
@@ -28,7 +28,7 @@ OAuth 使用发现元数据、动态注册的公开客户端、授权码、S256
|
||||
|
||||
## 页面复制提示词配置
|
||||
|
||||
在「设置与备份 → 连接 Agent」复制实际 MCP 地址和“Agent 使用教程”。支持远程 OAuth 的客户端填写此地址，选择 Streamable HTTP；在 WorthPath 网页登录，审核客户端名称、回调地址、资源，并选择连接权限。网页会回到已注册的精确回调地址并保留 state。客户端自行验证 state。
|
||||
在「设置与备份 → 连接 Agent → 开始连接」选择申请权限（默认 read,draft）及是否申请隐藏账户读取、修改权限（默认关闭），点击「复制 Codex 配置提示词」，发送给运行在本机、能够执行命令的 Codex。提示词明确授权它仅配置 worthpath 连接、使用 OAuth、保留其他配置并核对实际工具加载；命令由 Codex 执行，用户无需手动输入。用户仍须完成 WorthPath 网页登录和权限确认，当前会话无法加载新增工具时须重启客户端或新建会话。提示词不包含个人令牌，也不会修改账目。
|
||||
|
||||
权限选择只改变申请内容，不会立即改变现有连接授权；最终以网页确认和 connection_info 为准。这是可执行的配置指令，不是浏览器一键注册客户端；客户端缺少本机执行能力时需如实说明限制。
|
||||
|
||||
@@ -107,11 +107,12 @@ cd E:\WorthPath
|
||||
|
||||
| 环境变量 | 本地示例 | 用途 |
|
||||
| ------------------- | ------------------------- | ------------------------------------ |
|
||||
| MCP_PUBLIC_URL | http://localhost:3100/mcp | 规范资源 URL，路径必须 /mcp |
|
||||
| MCP_PUBLIC_URL | http://localhost:3100/mcp | 连接页显示/复制地址与提示词、OAuth 规范资源 URL，路径必须 /mcp |
|
||||
| MCP_ALLOWED_HOSTS | 留空 | Host 白名单（含端口），逗号分隔；`*` 允许所有 IP 和域名 |
|
||||
| MCP_WEB_URL | http://localhost:5173 | 网页授权及草稿确认入口 |
|
||||
| MCP_ALLOWED_ORIGINS | http://localhost:5173 | 精确 Origin 列表，逗号分隔，无通配符 |
|
||||
|
||||
本次没有新增环境变量。保留本机 .env；示例不含凭据。生产必须 HTTPS、COOKIE_SECURE=true、准确 WEB_ORIGIN。Host 匹配规范资源；带 Origin 的请求匹配白名单，无 Origin 的非浏览器客户端允许接入。不得用任意转发头构造授权地址。
|
||||
上线时应通过网络开关启用 HTTPS、Secure Cookie 并配置准确 WEB_ORIGIN；所有策略现由 apps/api/.env 控制。`MCP_ALLOWED_HOSTS` 未设置或留空时保留原有规则：允许规范资源 Host，非生产额外允许 localhost 和 127.0.0.1 对应端口。非空白名单替代默认列表，例如 `localhost:3100,127.0.0.1:3100,198.18.0.1:3100`；设置 `MCP_ALLOWED_HOSTS=*` 允许所有 IP 和域名，关闭 Host 防护，建议通过防火墙限制可访问的网络。修改 .env 后重启 API。该配置不改变 HTTPS 校验、OAuth 规范资源 URL、Origin 白名单或 Bearer 认证；MCP_PUBLIC_URL 和 MCP_WEB_URL 是否允许 HTTP 由 NETWORK_ALLOW_HTTP 控制。带 Origin 的请求匹配白名单，无 Origin 的非浏览器客户端允许接入。不得用任意转发头构造授权地址。
|
||||
|
||||
服务采用无状态 Streamable HTTP，请求结束关闭 transport/server；不共享用户认证上下文，不支持长期 GET SSE 或持久会话。代理转发规范 Host，禁用 MCP 响应缓冲，超时建议 330 秒；同时代理 /.well-known/、/authorize、/token、/register、/revoke 和 /api/。网站备份上传上限 512 MiB，ZIP 解压总计 1 GiB，代理配置对应 body 限制。日志不能保存 Authorization、密码、令牌或上传正文。
|
||||
|
||||
@@ -132,3 +133,11 @@ cd E:\WorthPath
|
||||
### 独立审核页面与草稿预览
|
||||
|
||||
OAuth 审核使用 /agent/authorize，草稿确认使用 /agent/operation；旧查询参数链接仍兼容。审核页显示申请范围、最终权限与授权期限。草稿按中文字段展示账户名称、金额、日期、备注及已有记录，用户确认后执行；过期或状态发生变化时不能提交。能力页面支持搜索，技术说明默认折叠。
|
||||
|
||||
### 局域网 HTTP 接入
|
||||
|
||||
NETWORK_ALLOW_HTTP=true 时支持配置的 HTTP MCP 服务和网页审核地址；NETWORK_ALLOW_HTTP_REDIRECTS 控制非本机 HTTP 回调。OAuth SDK 同步使用 HTTP 开关，继续执行 Bearer、PKCE 和精确回调匹配。服务地址与网页地址应配置为客户端能访问的地址，修改配置后重启 API。
|
||||
|
||||
### 统一网络配置
|
||||
|
||||
所有网络策略及中文说明见 apps/api/.env.example。API 与 Vite 网页开发服务共同读取 apps/api/.env，修改后重启。当前 .env 使用全网卡监听、Host/Origin 通配符、HTTP 和 HTTP 回调，Cookie 保持 HttpOnly 与 SameSite=strict。NETWORK_ALLOW_WILDCARD_ORIGINS 控制是否允许来源通配符；API_ALLOWED_HOSTS、MCP_ALLOWED_HOSTS 与 WEB_ALLOWED_HOSTS 分别控制各入口。限流开关、窗口和阈值也在环境文件中。详见 docs/network-settings.md。
|
||||
@@ -0,0 +1,26 @@
|
||||
# 网络访问配置
|
||||
|
||||
API 和网页开发服务共同读取 [环境配置模板](../apps/api/.env.example)，模板中每个变量都有中文说明。真实配置位于 apps/api/.env，已被 Git 忽略，不提交数据库连接或密码。
|
||||
|
||||
当前配置允许所有本机 IPv4 网卡、任意请求 Host 和有效的 HTTP/HTTPS 浏览器来源，并允许 HTTP MCP 服务及 HTTP 客户端回调。OAuth 的资源地址和网页授权地址仍使用配置的固定地址；远程客户端需要能访问该地址。登录、令牌、用户隔离及权限检查继续生效。
|
||||
|
||||
| 配置范围 | 变量 |
|
||||
| --- | --- |
|
||||
| API 监听与主机 | API_HOST、PORT、API_ALLOWED_HOSTS |
|
||||
| 网页开发服务 | WEB_HOST、WEB_PORT、WEB_ALLOWED_HOSTS、WEB_API_PROXY |
|
||||
| 网站来源 | WEB_ORIGIN、NETWORK_ALLOW_WILDCARD_ORIGINS |
|
||||
| MCP 地址与来源 | MCP_PUBLIC_URL、MCP_WEB_URL、MCP_ALLOWED_HOSTS、MCP_ALLOWED_ORIGINS、MCP_ALLOW_LOOPBACK_HOSTS |
|
||||
| HTTP 和回调 | NETWORK_ALLOW_HTTP、NETWORK_ALLOW_HTTP_REDIRECTS |
|
||||
| Cookie | COOKIE_SECURE、COOKIE_SAME_SITE、NETWORK_REQUIRE_SECURE_COOKIE |
|
||||
| HTTPS 响应策略 | NETWORK_HSTS、NETWORK_UPGRADE_INSECURE_REQUESTS |
|
||||
| 请求限流 | NETWORK_RATE_LIMIT_ENABLED、NETWORK_RATE_LIMIT_WINDOW_MS、NETWORK_AUTH_RATE_LIMIT_MAX、MCP_AUTH_RATE_LIMIT_MAX |
|
||||
|
||||
## 上线调整
|
||||
|
||||
将 NODE_ENV 改为 production，按实际域名设置 Host/Origin 白名单和 HTTPS 固定地址；关闭 HTTP、非本机 HTTP 回调及来源通配符，启用 Secure Cookie、HSTS、HTTPS 子资源升级。完整配置说明在环境模板中。显式环境开关优先于 NODE_ENV，修改环境名不会覆盖已设置的开放开关。
|
||||
|
||||
HTTP 使用 COOKIE_SECURE=false；COOKIE_SAME_SITE=none 必须使用 Secure Cookie。同站网页经 /api 代理访问保持 strict 即可。API 和网页开发服务都需重启才能读取新值，生产静态页面的访问端口由反向代理或部署服务配置。公网能否连接仍取决于路由、反向代理和防火墙；本次未修改这些系统设置。
|
||||
|
||||
## 验证
|
||||
|
||||
生产构建通过，43 项单元测试与 6 项真实 HTTP OAuth/MCP 测试通过。当前 HTTP 服务的 OAuth 发现返回 200，任意测试 Host/Origin 的 API 和 MCP 预检均返回 204。测试使用独立服务与临时账号，未修改真实用户账目。
|
||||
@@ -18,3 +18,5 @@
|
||||
最终验证：39 项单元测试（含工作区已有的 Host 配置测试）、20 项真实 MySQL 集成测试、6 项 OAuth/MCP 测试通过；生产构建与类型检查通过，25 项数据库迁移全部应用。
|
||||
|
||||
复验时当前环境的非本机 HTTP MCP 地址触发既有 HTTPS 校验。验证临时使用 localhost，未修改 .env；使用该非本机地址前仍须配置 HTTPS。
|
||||
|
||||
后续更新（2026-10-04 11:25，UTC+8）：HTTP 限制已改为环境配置，当前全网络开放配置及上线调整见 docs/network-settings.md。
|
||||
Reference in new issue
Block a user