快速部署

用离线安装包在一台服务器上部署 One Work 企业版。熟悉 Docker 的话约 15 分钟，全程不需要访问外网。

这里讲的是服务端。员工使用的桌面端是另一个安装包，装好服务端后，员工在桌面端填上服务器地址即可连接（见第六节）。

整个过程分六步：

1. 准备服务器，拿到安装包；
2. 安装（一条命令）；
3. 登录后台，取得初始密码并改密；
4. 激活授权（License）；
5. 配置域名和 HTTPS（正式使用前）；
6. 让员工连接。

一、准备

1.1 服务器要求

确认 Docker 可用：

docker --version
docker compose version        # 必须能输出版本号，说明 Compose v2 可用

确认端口没有被占用（应无输出），并放行防火墙：

ss -tlnp | grep -E ':(80|443) '
sudo ufw allow 80,443/tcp                                                                 # Ubuntu
sudo firewall-cmd --permanent --add-service={http,https} && sudo firewall-cmd --reload    # CentOS / RHEL

另外请确认服务器时间准确（开启 NTP）：证书有效期和授权到期都依赖系统时间。

1.2 获取并校验安装包

联系我们获取安装包 one-work-offline-<日期>.tar.gz，约 1.35 GB，拷到服务器上。我们会同时给你它的 SHA-256 值，拷完后核对：

sha256sum one-work-offline-*.tar.gz

包里有这些文件：

二、安装

1. 解压并进入目录

tar xzf one-work-offline-<日期>.tar.gz
cd one-work-offline-<日期>

这个目录就是安装目录，之后所有 docker compose 命令都要在这里执行。建议放在固定位置（如 /opt/one-work/），不要放在会被清理的临时目录。

2. 运行安装脚本

./install.sh

脚本会依次完成：

1. 把 4 个镜像导入 Docker；
2. 生成 .env：里面有一个随机的登录签名密钥 JWT_SECRET，并固定 Docker 项目名；
3. 创建 certs/ 目录（以后放你们自己的证书用）；
4. 生成 Caddyfile（默认是纯 HTTP 的 :80，先保证能打开）；
5. 恢复向量模型缓存；
6. 启动全部容器，等待后端就绪。

约半分钟完成，结束时会打印后台地址和取初始密码的命令。脚本可以重复运行，不会覆盖已有的 .env 和 Caddyfile。

安装时出现黄色警告 volume ... already exists but was not created by Docker Compose，是因为脚本在 Docker Compose 启动前先恢复了模型缓存，可以忽略。

3. 确认服务正常

docker compose ps       # 应看到 gateway、app、admin、embedding 四个服务都是 running
./status.sh             # backend、admin、embedding 都应显示 OK

向量服务刚启动时要加载模型，大约需要半分钟才就绪，status.sh 里 embedding 暂时显示 UNREACHABLE 属正常，稍等再查一次。

安装后目录里会多出这几个文件：

三、登录后台，取得初始密码并改密

3.1 打开后台

浏览器打开 http://服务器IP/admin，在服务器本机上也可以用 http://localhost/admin。输入不带斜杠的 /admin 会自动跳转。

默认是 HTTP，只适合先试用：密码和令牌是明文传输的。正式使用前请完成第五节配置 HTTPS。

3.2 取得初始管理员密码

系统首次启动时会生成一个随机的初始管理员密码（12 到 17 位），没有任何固定的默认密码。用户名是 admin。有三种方式拿到它。

方式一（推荐）：读密码文件，在安装目录里执行：

docker compose exec app cat /data/INITIAL_ADMIN_PASSWORD.txt

输出形如：

This file was generated once, the first time this server started with no admin password set.

Username: admin
Password: xxxxxxxxxxxxxx

Log in with this password, then change it immediately — you will be required to before you can do anything else. This file is not updated again after that; it is safe to delete once you have changed your password.

Password: 后面那一串就是初始密码。

方式二：从启动日志里找，适合文件被删除了的情况：

docker compose logs app | grep -A5 "Generated an initial admin password"

说明：

• 这个密码只在首次启动、且系统里还没有管理员密码时生成一次。改过密码之后，文件不会再更新，可以放心删除。
• 如果密码已经被改过又忘了：还有其它管理员的话，让他在「成员管理」里重置；只有一个管理员时请联系我们。

3.3 登录并强制修改密码

用 admin 和初始密码登录。系统会立刻要求你设置新密码，在改完之前，所有管理功能都会被拒绝。

填写当前密码（就是初始密码）和两次新密码，点确认修改。

新密码的要求：

• 长度 8 到 128 个字符；
• 不能是常见的弱口令，例如 password、12345678、qwertyui、abcdefgh；
• 对大小写、数字、符号没有强制要求，但建议使用足够长的强密码。

修改成功后会回到登录页，用新密码再登录一次，就进入管理后台首页：

员工日常使用的工作台在 http://服务器IP/，管理后台在 /admin，右上角的用户菜单可以互相切换。

四、激活授权（License）

4.1 为什么要激活

全新部署默认是免费档：只支持本地账号登录和基础使用，席位上限是 3（界面显示 1 / 3）。下面这些企业能力在免费档是未授权的：SSO 单点登录、审计日志、团队资源范围、仅管理员可见、细粒度 RBAC。要用它们，需要激活我们签发的授权。

4.2 激活步骤

1. 打开 License 页面。 左侧菜单进入「企业设置 → License 详情」（也可以点首页的 License 卡片）。免费档下页面是这样的：

2. 生成申请码。 点生成并复制申请码。页面会显示三项信息：实例 ID、SHA-256 指纹和申请码（ONEWORK-REQ- 开头），并提示「授权申请码已生成并复制」。

这三项把授权绑定到这台服务器。申请码已经复制到剪贴板；如果浏览器不允许自动复制，页面会提示你手动复制，这时从页面上把整段申请码选中复制即可（注意要复制完整，不要漏掉末尾）。

3. 把申请码发给我们。 通过联系我们提供的方式发送。我们会签发一个和这台服务器绑定的授权码（ONEWORK- 开头的一长串）。

4. 粘贴授权码并激活。 回到同一页面，把授权码粘贴到「粘贴授权码」输入框，点激活。成功时提示「授权已激活」，页面右上角显示生效中，并列出授权详情：

页面里能看到：客户名称、档位（企业档）、授权席位、到期时间、剩余天数、授权编号，以及各项上限。图中的客户名称是示例。

4.3 需要知道的事

• 授权绑定本实例（实例 ID 加部署指纹）。把系统迁移或恢复到另一台服务器、或者在同一台机器上重新安装成一个新实例后，原来的授权码不能用，需要拿新的申请码重新签发。在同一台服务器上备份再恢复不受影响。
• 到期前会提示「N 天后到期，请联系厂商续期」。到期后档位自动降级为免费档，数据不会被删除，激活新的授权码后恢复。
• 激活失败时页面会提示失败原因。最常见的原因是授权码复制得不完整，或者这个授权码不是为这台服务器签发的。
• 只有管理员可以操作这个页面。

五、配置域名与 HTTPS

编辑安装目录里的 Caddyfile，只改第一行的站点地址，按需增加几行，其余不要动，改完执行：

docker compose restart gateway

默认的第一行是 :80 {（纯 HTTP）。按你们的情况选一种：

A. 公网域名（证书自动申请并续期）：域名已解析到本机，且 80 / 443 对公网可达（证书验证走 80 端口）。

ai.example.com {

B. 自有证书：把证书和私钥放进安装目录的 certs/，它会被挂载到网关容器的 /certs。

ai.example.com {
	tls /certs/server.crt /certs/server.key

C. 内网 IP + 网关自签证书：员工电脑需要信任网关的根证书。纯 IP 站点必须在 Caddyfile 最顶部加上 default_sni（方案 B 用 IP 访问时同样需要），否则 HTTPS 握手会失败：

{
	default_sni 10.0.0.5
}

10.0.0.5 {
	tls internal

取出根证书，分发到员工电脑的受信任根证书里：

docker cp "$(docker compose ps -q gateway)":/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt

改完用这条命令确认能访问（-k 表示暂不校验证书，只在方案 C 用）：

curl -kI https://10.0.0.5/health      # 返回 200 即正常

六、让员工连接

员工安装 One Work 桌面端，点击窗口左下角的**「登录 / 加入项目组」**，按三步向导操作：

1. 连接服务器：填你访问后台用的地址，例如 https://ai.example.com 或 10.0.0.5，不用带 /admin。客户端会先检测这个地址是不是企业服务端，不是会直接提示；
2. 登录：用企业账号或 SSO 登录，登录在系统浏览器里完成，密码不经过桌面端；
3. 加入项目组：输入管理员给的邀请码（通过 SSO 或域名入伙加入的员工会自动加入）。

完成后，企业下发的模型、技能、工具和安全策略会自动出现在员工的客户端里，员工自己的会话和个人数据仍保存在本机。

在这之前，管理员需要先在后台完成基础配置（邀请成员、配置模型、授权资源），见管理员快速开局；员工侧的操作见工作成员快速开局。

使用方案 C（网关自签证书）时，员工电脑必须先信任根证书，否则桌面端会提示「无法连接远端服务器」。

七、日常运维

在安装目录里执行：

服务器重启后容器会自动恢复，前提是 Docker 本身开机自启（sudo systemctl enable docker）。

限制日志大小：Docker 默认不限制容器日志大小，长期运行可能占满磁盘。建议在 /etc/docker/daemon.json 里加上下面的配置，然后重启 Docker 并重建容器：

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "50m", "max-file": "5" }
}

备份

先停 app、admin（一两分钟），再打包数据卷。备份文件请放到另一台机器，并建议用 cron 每天执行：

docker compose stop app admin
docker run --rm -v one-work_dream-data:/data -v /backup:/backup alpine:3.20 \
  tar czf /backup/dream-data-$(date +%F).tgz -C /data .
docker compose start app admin
cp .env Caddyfile /backup/

数据卷名是 one-work_dream-data，可用 docker volume ls | grep dream-data 确认。alpine:3.20 是安装包自带的镜像，离线环境直接可用。刚装好的系统约 70 MB，随数据增长。后台「企业设置 → 备份与恢复」还能导出一份配置备份（只含配置，不含全部数据），建议一并保存。

恢复

在新装好的系统上（装之前先把备份的 .env 和 Caddyfile 放进安装目录）：

docker compose stop app admin
docker run --rm -v one-work_dream-data:/data -v /backup:/backup alpine:3.20 \
  sh -c 'rm -rf /data/* /data/.[!.]* ; tar xzf /backup/dream-data-<日期>.tgz -C /data'
docker compose start app admin

恢复到另一台服务器后，授权可能因机器不同而失效，见 4.3。

升级

1. 先按上面备份；
2. 在旧目录执行 ./uninstall.sh（数据保留）；
3. 解压新安装包到新目录，把旧目录里的 .env、Caddyfile 拷过来（用了自有证书还有 certs/）。必须拷 .env，否则安装脚本会生成新的密钥，所有人要重新登录；
4. 在新目录执行 ./install.sh，再用 ./status.sh 确认；
5. 用管理员账号登录后台，确认总览数据与升级前一致。

数据库迁移在启动时自动执行。迁移只进不退，要回滚必须先恢复升级前的备份，所以升级前的备份不能省。旧目录建议保留到新版本稳定之后再删。

八、Windows（Docker Desktop）

可以在 Windows 上用 Docker Desktop 部署：在 Docker Desktop 里开启 WSL 集成，然后在 WSL 终端（如 Ubuntu）里按上面的步骤执行 install.sh。注意：

• 安装包解压到 WSL 自己的目录（如 ~/one-work/），不要放在 /mnt/c，跨系统访问文件很慢；
• Docker Desktop 对员工超过 250 人或年营收超过 1000 万美元的企业需要付费授权；
• 容器设置了 unless-stopped，Windows 重启后先启动 Docker Desktop（它默认不开机自启），容器会自动恢复；
• 局域网内其它电脑访问时，需要在 Windows 防火墙放行 80 / 443；
• 仅建议用于试用和小团队，正式环境请用 Linux 服务器。

九、常见问题

反馈问题时请附上安装包里的 MANIFEST.txt、./status.sh 的输出和相关日志。