Ideon快速上手：3步用Docker部署你的自托管视觉工作区
Ideon快速上手：3步用Docker部署你的自托管视觉工作区
Ideon 是一款开源的自托管视觉工作区，它用一张无限画布替代零散的文件夹和标签页：笔记、待办、Git 仓库、链接和文件都能摆在同一张地图上。本文将带你用 Docker 在 3 步内完成部署，快速拥有属于自己的私有 Ideon 实例。
部署前准备：2个前置条件
开始前，请确认你的服务器满足以下两个条件：
| 前置条件 | 说明 |
|---|---|
| Docker | 用于运行应用容器 |
| Docker Compose v2 | 用于一键拉起应用 + 数据库两个服务 |
Ideon 的部署由两个服务组成（见 docker-compose.yml）：
- ideon-app：Ideon 主应用，基于 Dockerfile 构建的 Next.js 镜像；
- ideon-db：PostgreSQL 数据库，负责存储项目、画布和账号数据。
第1步：获取 Ideon 仓库
在服务器上克隆仓库（也可以直接下载 docker-compose.yml 和 env.example 两个文件）：
git clone https://gitcode.com/gh_mirrors/id/ideon.git
cd ideon
💡 如果你只想部署而不想克隆整个仓库，单独下载上面两个文件同样可以完成部署。
第2步：配置环境变量（关键！）
Ideon 的所有配置都集中在一个 .env 文件里。从官方模板复制一份：
cp env.example .env
打开 .env，至少需要设置以下几项（完整字段说明见 env.example）：
| 变量 | 作用 | 建议值 |
|---|---|---|
SECRET_KEY |
会话签名与数据加密的主密钥，必填 | openssl rand -hex 32 生成 |
DB_USER / DB_PASS |
PostgreSQL 用户名和密码 | 建议改成强密码 |
DB_NAME |
数据库名，默认 ideon |
默认即可 |
APP_PORT |
宿主机映射端口 | 默认 3000，冲突时改掉 |
APP_URL |
应用公网地址，用于邀请链接 | http://你的域名:3000 |
TIMEZONE |
服务器日志时区 | 如 Asia/Shanghai |
⚠️ 安全提醒：SECRET_KEY 一旦更换会使所有已登录会话立即失效；SMTP_* 系列变量用于配置邮件服务（邀请、魔法链接等），本地体验可以先留空，后续再补。
第3步：一键启动并访问
配置完成后，在项目根目录执行：
docker compose up -d
Docker Compose 会先等待数据库健康检查通过，再启动应用（两个服务都内置了 healthcheck）。稍等片刻，打开浏览器访问：
http://localhost:3000
首次访问会进入初始化页面，填写邮箱、用户名和密码，即可创建第一个管理员账号并开始使用画布。
验证部署是否成功
Ideon 内置了健康检查接口，可以直接验证数据库与应用状态：
curl http://localhost:3000/api/health
返回 {"status":"ok",...} 即表示部署成功。该接口的实现位于 src/app/api/health/route.ts，它会对数据库执行一次查询来确认连通性。
常用运维命令速查
| 操作 | 命令 |
|---|---|
| 查看状态 | docker compose ps |
| 查看日志 | docker compose logs -f ideon-app |
| 停止服务 | docker compose stop |
| 停止并删除容器 | docker compose down |
| 数据备份 | 备份 ideon-db-data 卷 + ideon-app-data 卷 |
两个数据卷的含义：ideon-db-data 存放数据库，ideon-app-data 挂载到容器内 /app/storage，存放头像、上传文件和实时协作（Yjs）文档。
常见问题 FAQ
Q1：端口 3000 被占用怎么办？
在 .env 中修改 APP_PORT=3001，重启后访问对应端口即可。
Q2：如何升级到新版本？
docker compose pull
docker compose up -d
Q3：想基于源码本地构建镜像（开发模式）？ 仓库提供了 docker-compose.dev.yml 覆盖文件和 compose.sh 脚本，例如：
./compose.sh build
./compose.sh start
详见 CONTRIBUTING.md。
Q4：忘记密码或想配置邮件邀请？
在 .env 中补齐 SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASSWORD 等字段后重启，即可启用邀请邮件和密码找回功能。
写在最后
至此，你已经在 3 步内完成了 Ideon 自托管视觉工作区的完整部署。接下来可以：
- 创建第一个项目，把笔记和待办摆上无限画布；
- 嵌入 GitHub / GitLab / Gitea 仓库，让代码与文档同屏协作；
- 开启 Git 版本同步，把画布结构作为文件提交到你的仓库。
祝部署顺利，享受空间化组织项目的全新体验！🚀