diff --git a/.gitignore b/.gitignore index 56e78a8..4e2e167 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,9 @@ # 本地配置可能含凭据,构建/文档生成目录不作为源码提交。 .env +.env.* +*.env +!.env.example +!.env.*.example +!*.env.example /bin/ /api-docs/ diff --git a/deploy/examples/.env.dev.example b/deploy/examples/.env.dev.example new file mode 100644 index 0000000..39b03bb --- /dev/null +++ b/deploy/examples/.env.dev.example @@ -0,0 +1,23 @@ +# 开发环境模板,无真实凭据。真实副本可保存为 .env.dev,不提交 Git。 +# Foundry 当前要求 HTTPS origin;本地使用时需要对应的开发 TLS 代理。 +PUBLIC_ORIGIN=https://localhost:8443 +HOST=127.0.0.1 +PORT=8080 +FOUNDRY_PROJECTS={"notes":"http://localhost:3000/auth/callback"} + +# 以下留空项必须配置,数据库和 OAuth 应使用开发环境专用凭据。 +DATABASE_URL= +GOOGLE_CLIENT_ID= +GOOGLE_CLIENT_SECRET= + +# 若启用 DSL 中声明的 email,需要完整配置 SMTP;不是读取 YAML 后自动启用。 +SMTP_HOST= +SMTP_PORT=465 +SMTP_USERNAME= +SMTP_PASSWORD= +SMTP_FROM= + +# 可选 worker:配置后须确保 socket 可连接、授权文件有效。 +# CLI 的 auth.json 由 worker 独立保管,不放入 Core 的 env。 +FOUNDRY_CODEX_SOCKET= +FOUNDRY_CODEX_GRANTS= diff --git a/deploy/examples/.env.prod.example b/deploy/examples/.env.prod.example new file mode 100644 index 0000000..774975c --- /dev/null +++ b/deploy/examples/.env.prod.example @@ -0,0 +1,22 @@ +# 生产环境模板,无真实凭据。真实副本保存在部署服务器或密钥管理系统中。 +# 此模板用于讨论未来的运行时配置,当前 release.sh 尚未支持统一 prod env 文件。 +PUBLIC_ORIGIN=https://api.notes.example.com +HOST=0.0.0.0 +PORT=8080 +FOUNDRY_PROJECTS={"notes":"https://notes.example.com/auth/callback"} + +# 部署时从生产密钥存储注入,不能留空启动,也不能写进二进制或构建产物。 +DATABASE_URL= +GOOGLE_CLIENT_ID= +GOOGLE_CLIENT_SECRET= + +# 邮件能力需要完整的生产 SMTP 配置。 +SMTP_HOST= +SMTP_PORT=465 +SMTP_USERNAME= +SMTP_PASSWORD= +SMTP_FROM= + +# 容器内路径;部署器还需为此实例挂载相应 socket 和授权目录。 +FOUNDRY_CODEX_SOCKET=/run/foundry-codex/worker.sock +FOUNDRY_CODEX_GRANTS=/etc/foundry-codex/projects.json diff --git a/deploy/examples/README.md b/deploy/examples/README.md new file mode 100644 index 0000000..2c25a38 --- /dev/null +++ b/deploy/examples/README.md @@ -0,0 +1,38 @@ +# BaaS 打包声明与环境配置示例 + +这些文件是 DSL 设计草案,不是已经实现的打包接口。现有 Go 入口、CI 和部署脚本均未接入它们;不要直接用这些示例执行生产发布。 + +## 文件职责 + +- `backend.yaml`:声明后端名称、需要的能力、构建平台和部署要求,可提交 Git。 +- `.env.dev.example`:开发运行配置模板,可提交 Git;真实 `.env.dev` 仅保存在本地。 +- `.env.prod.example`:生产运行配置模板,可提交 Git;真实生产值由部署环境保管。 + +`secretRef` 和 `credentialsRef` 只是未来部署器解析的逻辑名称,不是密码,也不是当前支持的环境变量插值语法。密钥引用如何映射到环境变量或文件,以及 dev/prod 如何覆盖域名等字段,尚待定义。Core 的 Codex IPC/授权路径与 worker 的 CLI 登录是不同配置;`notes-codex` 对应的专用登录不应提供给 Core。 + +`features` 暂时只表达期望。关闭能力是从编译产物中排除模块,还是只在运行时关闭注册,尚待确定。现有入口仍要求 Google 凭据,email 需要完整 SMTP 配置,YAML 不会自动改变这些行为。 + +## 编译与运行环境的边界 + +目标流程为: + +```text +源码 + backend.yaml → 远程构建 → 程序与不含密钥的打包声明 + ↓ + 部署时注入对应环境配置 → 启动实例 +``` + +生产凭据只在部署/运行时提供。常规 Go 编译无需读取生产数据库密码或 OAuth Secret。同一个构建产物可以在配置兼容的开发和生产环境运行;它们各自使用独立的数据库、账号和凭据。环境文件不会被 Go 自动加载,需要启动器将配置放入进程环境,或由 Docker 的 `--env-file` 读取。 + +## 生产 env 的保管 + +可采用每实例一个受保护目录,例如服务器上的 `/etc/foundry/instances/notes-backend/`,真实配置保存为其中的 `prod.env`。这是未来部署布局的示例,当前脚本不会创建或读取该位置。 + +- 目录设为 `700`、文件设为 `600`,所有者为需要读取它的部署账号。 +- 凭据通过受控运维过程或密钥管理系统配置;部署器读取后向目标容器注入,不复制进发布目录、镜像或构建归档。 +- CI 如需提供密钥,使用受保护的 Actions Secrets,并仅允许可信生产发布作业访问;普通 PR、构建和测试不应取得生产密钥。 +- 不在日志中输出 env 内容或开启包含凭据的命令跟踪。具备 root、Docker 管理或相应进程访问权限的账号仍可能读取运行时环境,文件权限不能隔离这些管理员。 + +仓库忽略 `.env`、`.env.*` 和 `*.env`,保留 `*.example` 模板。Git 忽略只能防止通常的误添加,不是密钥存储机制,也不会移除已经被跟踪的文件。 + +现有生产链路仍从服务器的 `/opt/endoleap-infra/foundry/database.env` 读取数据库配置,并从 Actions Secrets 注入 OAuth 凭据;这里只记录未来 DSL 的设计方向,不改变当前生产行为。 diff --git a/deploy/examples/backend.yaml b/deploy/examples/backend.yaml new file mode 100644 index 0000000..0b5ba29 --- /dev/null +++ b/deploy/examples/backend.yaml @@ -0,0 +1,24 @@ +# 打包 DSL 草案:目前仅用于讨论,现有构建和部署脚本尚不会读取此文件。 +apiVersion: foundry/v1 +kind: Backend + +name: notes-backend + +features: + auth: + providers: [google, email] + platform: true + research: false + codex: true + +build: + target: + os: linux + arch: amd64 + +deploy: + domain: api.notes.example.com + database: + secretRef: notes-database + codex: + credentialsRef: notes-codex