配置系统设置指南
从零开始配置 HackerStart 的环境变量、数据库连接和管理面板
本指南将带你从零开始，逐步完成 HackerStart 配置系统的初始化。完成后你将拥有一个可用的管理面板（/admin/config），可以在线管理大部分运行时配置。
前提条件
开始之前，请确认以下工具已安装：
- Node.js v22+（
node --version确认） - pnpm（
pnpm -v确认，未安装：npm install -g pnpm） - InsForge 服务（本地 Docker 或 InsForge Cloud）
已完成《快速开始》中的项目克隆、依赖安装和 .env 文件复制。
配置系统两层设计
HackerStart 的配置分两层：
- 部署级（.env 文件）：数据库连接、加密密钥、租户模式等。修改后需要重启服务。
- 运行时（/admin/config 面板）：支付密钥、邮件配置、存储设置等。修改后即时生效，无需重启。
先配好部署级，再配运行时。
第一步：启动 InsForge 服务
配置系统依赖 InsForge 提供的数据库。如果你已经在《快速开始》中配置了 InsForge 环境变量，可以跳过此步骤。
方式一：本地 InsForge（Docker）
使用 InsForge CLI 在本地启动：
insforge start启动后，将 InsForge 提供的连接信息填入 .env：
INSFORGE_URL=http://localhost:10700
INSFORGE_ANON_KEY=你的匿名密钥
INSFORGE_API_KEY=你的API密钥
VITE_INSFORGE_URL=http://localhost:10700
VITE_INSFORGE_ANON_KEY=你的匿名密钥方式二：InsForge Cloud
在 InsForge Dashboard 中获取连接信息，填入 .env。
DATABASE_URL 是可选的
配置系统的高级功能（如 /admin/config 管理面板）需要 DATABASE_URL 直连 InsForge 管理的 PostgreSQL。如果不配置，应用仍然可以正常运行，但管理面板不可用。详见《环境变量配置》。
第二步：生成加密密钥
配置系统需要两个独立的加密密钥。在终端中执行以下命令各一次：
# 生成 Session 加密密钥（用于登录状态）
openssl rand -base64 32
# 生成配置加密密钥（用于加密存储 secret 类配置项）
openssl rand -base64 32将生成的两个值分别填入 .env：
# Session 加密密钥 — 保护登录状态
SESSION_SECRET=你生成的第一个密钥
# 配置加密密钥 — 保护存储在数据库中的敏感配置（如支付密钥、SMTP 密码）
CONFIG_ENCRYPTION_KEY=你生成的第二个密钥密钥安全
CONFIG_ENCRYPTION_KEY丢失后，已加密的配置值将不可读（回退到默认值）- 密钥轮换需要重新保存所有加密配置
- 不要将密钥提交到版本控制
第三步：租户模式配置
租户模式决定了你的 SaaS 应用如何组织用户和工作空间。这些是配对变量——不带 VITE_ 的（服务端）和带 VITE_ 的（客户端）值必须一致，否则应用启动时会报错。
对于大多数项目（单租户模板），默认值即可：
# 租户模式：single（单租户）或 multi（多租户）
TENANCY_MODE=single
VITE_TENANCY_MODE=single
# 租户 UI 显示：hidden（隐藏）或 visible（可见）
TENANT_UI=hidden
VITE_TENANT_UI=hidden
# 角色系统：true 或 false
ROLES_ENABLED=false
VITE_ROLES_ENABLED=false
# 组织模式：off 或 hierarchical
ORG_MODE=off
VITE_ORG_MODE=off如果你需要多租户模式（每个注册用户自动创建独立工作空间），将 TENANCY_MODE 和 VITE_TENANCY_MODE 改为 multi，TENANT_UI 和 VITE_TENANT_UI 改为 visible。
组织创建控制（启用组织模式后）
当你设置 ORG_MODE=hierarchical 后，还有两个运行时配置可以在管理面板中调整，不需要修改环境变量：
| 配置项 | 默认值 | 说明 |
|---|---|---|
组织创建权限 (tenancy.orgCreation) | admin_only | 谁能创建组织：admin_only（仅平台管理员）或 open（所有登录用户） |
组织数量上限 (tenancy.orgMaxCount) | 1 | 最多允许创建的组织数量。0 表示不限制 |
典型场景：
- 单组织部署（如 Coding Girls Club）：保持默认
admin_only+1，平台管理员创建唯一组织，其他用户只能加入 - 平台型 SaaS：改为
open+0，任何登录用户都能创建组织，不限数量
这两个配置项在 /admin/config 面板的「租户」分组中，部署后可随时在线修改。
第四步：内容开关
控制站点中哪些内容模块对用户可见。同样是配对变量：
# 文档
CONTENT_DOCS_ENABLED=true
VITE_CONTENT_DOCS_ENABLED=true
# 博客
CONTENT_BLOG_ENABLED=true
VITE_CONTENT_BLOG_ENABLED=true
# 更新日志
CONTENT_CHANGELOG_ENABLED=true
VITE_CONTENT_CHANGELOG_ENABLED=true
# 路线图
CONTENT_ROADMAP_ENABLED=true
VITE_CONTENT_ROADMAP_ENABLED=true
# 法律页面（隐私政策、服务条款等）
CONTENT_LEGAL_ENABLED=true
VITE_CONTENT_LEGAL_ENABLED=true根据你的实际需要开关对应模块。
第五步：平台管理员自举
在 .env 中添加你的登录邮箱，用于自动成为首位平台管理员：
PLATFORM_ADMIN_BOOTSTRAP_EMAILS=你的邮箱@example.com工作原理：当 platform_admins 数据库表为空时，名单中的邮箱对应的用户首次访问 /admin/config 即自动成为 platform_owner。
引导完成后
引导完成后，管理权限完全由数据库控制。你可以移除 .env 中的 PLATFORM_ADMIN_BOOTSTRAP_EMAILS，之后通过管理面板添加或管理其他管理员。最后一名活跃的 platform_owner 无法被降级，确保平台始终有管理员。
第六步：启动并验证
配置完成后，启动开发服务器：
pnpm dev然后按以下步骤验证：
- 打开 http://localhost:3000，注册一个账号（使用你在
PLATFORM_ADMIN_BOOTSTRAP_EMAILS中填写的邮箱） - 登录后访问 Dashboard，如果你是管理员，会看到 Configuration Panel 入口卡片
- 点击进入 http://localhost:3000/admin/config
- 如果配置正确，你将看到完整的配置管理面板
管理员角色说明
| 角色 | 权限 |
|---|---|
platform_owner | 全部权限：读取、修改、删除配置，管理其他管理员 |
platform_admin | 读取和修改配置，不能管理其他管理员 |
platform_viewer | 只能查看配置，不能修改 |
常见问题
管理面板显示 "Network request failed"
这通常表示数据库连接失败或 InsForge 后端未启动。检查：
DATABASE_URL是否正确，数据库是否可连接- InsForge 后端是否在运行（配置系统依赖它处理用户认证）
管理面板没有出现 Configuration Panel 入口
Dashboard 上的管理入口卡片仅在当前用户是平台管理员时显示。确认：
PLATFORM_ADMIN_BOOTSTRAP_EMAILS中填写了你的注册邮箱- 你使用的登录邮箱与配置中的完全一致（区分大小写）
- 数据库已正确创建
platform_admins表
配置项显示为「已锁定」
如果某个配置项在管理面板中显示为锁定状态，说明 .env 中已经通过环境变量设置了该值。环境变量优先级最高，锁定后无法通过面板编辑。如需修改，直接编辑 .env 文件并重启服务。
配置优先级
从高到低：
- 环境变量（
.env文件）— 锁定配置项，面板不可编辑 - 租户级别覆盖（
tenant_config_overrides表）— 工作区维度的独立配置 - 全局数据库配置（
app_config_values表）— 通过管理面板设置 - Schema 默认值（
src/config/app-config/schema.ts）— 代码中的默认值
详细的配置项说明请参考《环境变量配置》文档。