{{wikiTitle}}
Docker安装教程
陀螺匠独立版 · Docker 安装指南
适用版本：V2.6 及以后
官方文档：https://doc.crmeb.com/tuoluojiang
一、为什么推荐 Docker 安装
强烈推荐使用 Docker 完成安装与日常运行。
自 V2.6 起，AI 知识库、RAG 检索、文档 OCR 等能力依赖特定系统组件。Docker 一键提供对齐版本的 PHP / MySQL / Redis Stack / OCR 工具链；裸机需自行安装 PHP 扩展、swoole_loader、Redis Stack、tesseract 等，排查成本高，也更容易因版本不一致导致功能不可用。
| 能力 | Docker 已内置 | 说明 |
|---|---|---|
| RAG 向量检索 | Redis Stack + RediSearch | 知识库向量 KNN 召回；普通社区版 Redis 不支持 RediSearch |
| 知识库 OCR | tesseract（中/英）+ ImageMagick | 多图 PDF、分段内嵌图片可识别为文字；默认完整 ocr 镜像 |
| PDF 文本提取 | poppler-utils（pdftotext） |
文档解析链路开箱可用 |
| PHP 运行时 | PHP 8.0 + Swoole + swoole_loader | 与官方运行时一致，免手工匹配扩展 |
| 数据与缓存 | MySQL 8 + Redis Stack 同编排 | 一键启停；MySQL / Redis 默认仅绑定本机，降低误暴露风险 |
| 运维体验 | manage.sh 统一管理 |
启停、备份、升级、查看端口与日志 |
轻量场景若不需要 OCR，可在
server/docker/.docker.env将PHP_IMAGE_TARGET=base后重建；知识库 RAG 仍依赖 Redis Stack，不建议改用普通 Redis。
Linux / macOS 推荐使用 server/docker/manage.sh 管理环境；Windows 可按下文使用 Docker Desktop 与 docker compose 启动。
二、项目目录结构
当前项目为单体结构（tuoluojiang），后端与 Docker 环境均在 server/ 下：
tuoluojiang/ # 仓库根目录
├── admin/ # 管理端前端（PC）
├── chat/ # 会话前端
├── uniapp/ # 移动端前端
└── server/ # 服务后端（PHP / LaravelS）★ 安装与 Docker 在此
├── app/
├── public/ # 前端构建产物同步目录（admin / chat / work 等）
├── database/
├── .env.example
├── .version
└── docker/ # Docker 编排与管理脚本 ★
├── manage.sh # 推荐入口：启停 / 备份 / artisan 等
├── docker-compose.yml
├── .docker.env # 基线配置（端口、镜像目标等）
├── .docker.instance.env # 当前实例配置（Windows 启动时使用）
├── php/
├── mysql/
└── redis/
要点：
- Docker 目录实际路径是
server/docker/，不是仓库根下的docker/。 - 所有
manage.sh命令都在server/docker/下执行；容器挂载的是server/作为应用根（.env、artisan、业务代码均在此）。 - 若拿到的是「仅后端」完整安装包（解压后直接含
app/、artisan、docker/），则该包根目录等价于上表中的server/，此时进入包内的docker/即可，命令写法相同。
三、环境要求
| 项 | 建议 |
|---|---|
| 操作系统 | Linux / macOS / Windows（需 Docker Desktop 或等价环境） |
| Docker | Docker Engine 20.10+ 或 Docker Desktop |
| 内存 | 建议 ≥ 4GB |
| 磁盘 | 建议预留 ≥ 5GB（首次构建镜像耗时更长、占空间更多） |
| 端口 | 默认应用 20300、MySQL 3376、Redis 6389（冲突时由 manage.sh 自动换实例编号） |
宿主机只需安装 Docker，不必自行安装 PHP、MySQL、Redis、Swoole、tesseract 等。
四、首次安装（推荐流程）
1. 准备安装包
解压 V2.6 完整安装包（或拉取对应代码）到目标目录，确认存在：
server/docker/manage.sh
（仅后端包则为包根目录下的 docker/manage.sh。）
2. 启动服务
Windows 环境：
- 首先安装并启动 Docker Desktop 客户端，等待 Docker 引擎就绪。
- 按照前端打包教程，将各前端项目打包，并将构建产物放到
server/public/下对应目录。 修改
server/docker/.docker.instance.env文件，确保HOST_APP_PORT和APP_PORT一致。若该文件不存在，先复制同目录下的.docker.env为.docker.instance.env，再补充或修改这两个变量，例如：HOST_APP_PORT=20200 APP_PORT=20200在 PowerShell 中进入
server\docker目录，执行以下命令即可启动项目（以下路径从仓库根目录出发）：cd server\docker docker compose --env-file ./.docker.instance.env up
首次启动需要拉取镜像、构建运行环境并初始化依赖，速度会比较慢，请耐心等待。上述命令会在当前终端持续显示日志，运行期间请保持终端打开。
Linux / macOS 环境：
cd server/docker
./manage.sh start
首次启动会自动：
- 分配 / 绑定当前实例（端口、容器名）
- 构建并启动 PHP、MySQL、Redis Stack
server/根目录无.env时，从.env.example生成并写入容器内数据库 / Redis 地址- 按需执行
composer install，加载 Linux 版swoole_loader
首次构建镜像可能较久，请耐心等待。
3. 确认服务状态
Windows 在 server\docker 目录另开一个 PowerShell 窗口，执行：
docker compose --env-file ./.docker.instance.env ps
Linux / macOS 执行：
./manage.sh status
./manage.sh info
确认 PHP、MySQL、Redis 均已正常运行。Windows 访问端口以 .docker.instance.env 中的 HOST_APP_PORT 为准；Linux / macOS 以 ./manage.sh info 为准（默认多为 http://localhost:20300）。
4. 打开安装页面
浏览器访问：
http://localhost:20300/install
（端口若已变更，Windows 请替换为 HOST_APP_PORT 的值，Linux / macOS 请替换为 info 中显示的应用端口。）
按页面提示完成安装。安装流程会创建业务数据表并写入初始化数据。
安装页数据库连接一般使用（容器内默认，通常无需改）：
| 项 | 值 |
|---|---|
| 主机 | mysql |
| 端口 | 3306 |
| 数据库 | tuoluojiang |
| 用户名 | root |
| 密码 | 见 server/docker/.docker.env（默认多为 123456） |
5. 安装完成后登录
安装成功后访问应用首页（同端口，去掉 /install），使用安装时设置的管理员账号登录。
建议接着完成：
- 系统设置 → 一号通：配置后可使用一号通会话 / 向量模型
- AI → MCP 配置：按需开启读 / 写权限
- 为角色分配 AI 会话、知识库、MCP 配置、一号通 等菜单权限
- 按需创建知识库并关联到 AI 应用
五、日常管理命令
均在 server/docker/ 目录执行：
cd server/docker
./manage.sh start # 启动当前绑定实例
./manage.sh stop # 停止
./manage.sh restart # 重启
./manage.sh status # 运行状态
./manage.sh logs # 日志
./manage.sh info # 当前实例名、端口等
./manage.sh list # 列出本机实例
./manage.sh backup # 备份数据库（生成 SQL 文件到 server/docker 目录）
./manage.sh restore <文件.sql> # 从备份恢复（会覆盖当前库数据，慎用）
./manage.sh artisan ... # 在容器内执行 artisan 命令
./manage.sh help # 全部命令说明
常用示例：
# 清理缓存
./manage.sh artisan cache:clear
# 版本升级（示例升级到 2.6）
./manage.sh backup
./manage.sh artisan tl:up --target=2.6 --skip-composer --pretend # 先模拟
./manage.sh artisan tl:up --target=2.6 --skip-composer --force # 再正式执行
./manage.sh restart
业务版本迁移请使用
tl:up，不要使用php artisan migrate（不会扫描database/migrations/v{版本}/子目录）。
六、可选配置
基线配置文件：server/docker/.docker.env（一般无需修改）。
| 变量 | 含义 | 默认倾向 |
|---|---|---|
HOST_APP_PORT |
应用宿主机端口基线 | 20300 |
HOST_MYSQL_PORT |
MySQL 宿主机端口 | 3376 |
HOST_REDIS_PORT |
Redis 宿主机端口 | 6389 |
HOST_PUBLISH_BIND |
MySQL/Redis 宿主机绑定 | 127.0.0.1（仅本机） |
PHP_IMAGE_TARGET |
PHP 镜像目标 | ocr（完整 OCR）；可改为 base 加快构建 |
修改 .docker.env 后执行：
./manage.sh stop
./manage.sh start
验证 OCR 完整镜像（可选）：
./manage.sh exec php
# 进入容器后执行：
tesseract --list-langs # 应能看到 chi_sim、eng
convert -version
exit
关于 MySQL / Redis 端口安全
默认 HOST_PUBLISH_BIND=127.0.0.1，不对公网开放。远程用 Navicat 等工具时，请走 SSH 隧道（数据库主机填 127.0.0.1，端口见 ./manage.sh info）。确需局域网直连时，可将绑定改为 0.0.0.0 后重建（不推荐对公网开放）。
七、多实例说明
同一套 server/ 代码目录只允许一套 Docker 容器。 需要并行多套时，请使用独立目录或 git worktree，再在新目录执行：
cd /path/to/另一份代码/server/docker
./manage.sh start --new
禁止在同一 server/ 目录反复 start --new 拉多套（会共用 .env / install.lock / storage，互相干扰）。
八、清空数据重新安装
仅适用于测试环境或确认可丢弃全部业务数据的场景。
cd server/docker
./manage.sh backup # 强烈建议先备份
./manage.sh stop
# 删除 MySQL 数据卷（实例名以 ./manage.sh info 为准，默认多为 tuoluojiang_mysql_data）
docker volume rm tuoluojiang_mysql_data
./manage.sh start
然后重新打开 /install 安装页。删除数据卷会清空 Docker MySQL 中的全部数据，生产环境务必先备份。
九、常见问题
1. 首次启动很慢？
正常。需拉取基础镜像并构建 PHP（含 OCR 时更大）。可改用 PHP_IMAGE_TARGET=base 加快构建，但会弱化 OCR。
2. 端口被占用？
使用 ./manage.sh start --new（需在尚无实例的独立代码目录），或调整 .docker.env 中的端口基线后重建。
3. 知识库检索很慢 / 向量能力异常？
确认使用的是 Docker 自带的 Redis Stack，不要换成普通 Redis。从普通 Redis 迁到 Stack 后，可在容器内执行向量回填相关命令（见产品文档）。
4. PDF / 图片文字识别不到？
确认当前为 ocr 完整镜像（默认），且未将 PHP_IMAGE_TARGET 设为 base。可用上文 tesseract --list-langs 自检。
5. 安装页打不开？
先执行 ./manage.sh status / logs 查看 PHP 是否 healthy；确认浏览器端口与 ./manage.sh info 一致。
十、相关文档
- Docker 目录技术说明：
../server/docker/README.md（开发向细节） - 官方在线文档：https://doc.crmeb.com/tuoluojiang
如有问题，请联系官方客服。
{{cateWiki.like_num}}人点赞
0人点赞
{{cateWiki.page_view_num}}人看过该文档
5687人看过
{{item.page_view_num}}
{{item.like ? item.like.like_num : 0}}
{{item.comment ? item.comment.comment_num : 0}}
