用 Docker 自部署
目标：用一条命令，在一台服务器上运行 Hub、管理端和 PostgreSQL 16。
开始前：
- Windows、macOS：Docker Desktop，使用 Linux 容器模式。
- Linux：Docker Engine 和 Compose v2。
- 主机上有 Python 3.12 或更新版本。主机上不需要安装 Node.js 或数据库。
- 首次构建需要联网，以及 20 GB 可用磁盘空间。
镜像在你的机器上从源码构建，使用 Docker Hub、npm、PyPI 和 PostgreSQL 官方镜像。
1. 启动
在源码目录运行：
python ops/self-host/deploy.py up
macOS 和 Linux 也可以用 python3 ops/self-host/deploy.py up，还可以运行 ops/self-host/deploy.cmd up 或 sh ops/self-host/deploy.sh up。
首次运行会：
- 建立私有配置，生成独立的数据库密码、初始管理员密码、签名密钥和连接器加密密钥；
- 构建管理端和 Hub 镜像；
- 迁移新数据库；
- 执行健康检查。
健康检查通过后显示访问地址：**http://127.0.0.1:18989**。构建时间取决于网络和镜像源。
2. 获取管理员密码
python ops/self-host/deploy.py credentials
账号是 admin。登录后在 用户管理 里修改密码。credentials 显示的始终是首次启动时的密码，不会重置你改过的密码。正常的启动和构建日志不会输出密码。
3. 连接客户端
按连接桌面客户端操作，填这个 Hub 的地址。
管理实例
| 命令 | 作用 |
|---|---|
python ops/self-host/deploy.py status | 查看容器状态 |
python ops/self-host/deploy.py logs | 查看日志 |
python ops/self-host/deploy.py stop | 停止这个实例，数据库、文件和密钥都保留 |
python ops/self-host/deploy.py up --no-build | 用已构建的镜像重新启动 |
python ops/self-host/deploy.py up | 更新源码后重新构建并启动 |
stop 不会删除数据卷，也不会清理其他 Docker 资源。构建或健康检查失败时，命令会报告失败，不会启动残缺的服务，可以直接重试。
使用其他端口或目录
python ops/self-host/deploy.py up --port 18990 --data-dir "/srv/soduwork-team"
目录必须在源码目录之外，并且为空。每个目录对应独立的 Compose 项目和数据卷，之后的每条命令都要带同一个 --data-dir。--port 只在首次启动时生效。
开放给团队访问
Hub 只映射到 127.0.0.1，PostgreSQL 不映射到主机。要让团队访问：
-
在这台服务器上配置 HTTPS 反向代理，转发到
127.0.0.1:18989。代理要支持 WebSocket 和长时间的流式响应。 -
首次启动时设置公开地址：
python ops/self-host/deploy.py up --public-url https://work.example.com把
work.example.com换成你的域名。只填 HTTPS 源地址，不带/api、账号或查询参数。
已有实例要改地址：先停止，修改它的 deployment.json 里的 publicUrl，再运行 python ops/self-host/deploy.py up --no-build。
启动器不会申请证书、修改 DNS 或防火墙。代理上线后，通过代理检查登录、文件上传、WebSocket 和流式对话。
数据存放位置
| 系统 | 私有配置目录 |
|---|---|
| Windows | %LOCALAPPDATA%\SoduWork\self-host |
| macOS | ~/Library/Application Support/SoduWork/self-host |
| Linux | $XDG_DATA_HOME/soduwork/self-host，或 ~/.local/share/soduwork/self-host |
deployment.json里有这个实例的密码和密钥，请妥善保管，不要提交到仓库。- 数据库和业务文件保存在 Docker 命名卷中，卷名以
deployment.json里的project值开头。 - 配置目录不是数据备份。重置或卸载 Docker Desktop、手动删除数据卷，都会删除数据。
工作在哪里执行
Hub 容器内不运行 Agent。本机工作在每位用户的客户端里执行；云端工作需要在管理端登记独立的 Runner（见 Runner 与云端环境）。容器以普通用户运行，不挂载 Docker socket。