### Example Output of Running Containers

Source: https://pandawiki.docs.baizhi.cloud/node/019b1176-3f58-7cd5-b93c-71c98c1d9f97

This output confirms that all 12 PandaWiki services have been successfully started and are running. Each line indicates a container that is now operational.

```text
[+] Running 12/12
 ✔ Container panda-wiki-minio     Running                                                                              0.0s 
 ✔ Container panda-wiki-caddy     Running                                                                              0.0s 
 ✔ Container panda-wiki-postgres  Running                                                                              0.0s 
 ✔ Container panda-wiki-app       Running                                                                              0.0s 
 ✔ Container panda-wiki-redis     Running                                                                              0.0s 
 ✔ Container panda-wiki-nats      Running                                                                              0.0s 
 ✔ Container panda-wiki-qdrant    Running                                                                              0.0s 
 ✔ Container panda-wiki-raglite   Running                                                                              0.0s 
 ✔ Container panda-wiki-api       Running                                                                              0.0s 
 ✔ Container panda-wiki-nginx     Running                                                                              0.0s 
 ✔ Container panda-wiki-crawler   Running                                                                              0.0s 
 ✔ Container panda-wiki-consumer  Running                                                                              0.0s
```

--------------------------------

### Install PandaWiki

Source: https://pandawiki.docs.baizhi.cloud/node/01971650-cb16-7957-96fd-26207f49f264

Execute this command to install PandaWiki on a Linux system with Docker 20.x or higher. Follow the on-screen prompts during installation.

```bash
bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"
```

--------------------------------

### Start PandaWiki Services with Docker Compose

Source: https://pandawiki.docs.baizhi.cloud/node/01971602-bb4e-7c90-99df-6d3c38cfd6d5

Use this command to start the PandaWiki services in detached mode (-d) using the docker-compose.yml file and the .env configuration. This command should be run from the PandaWiki installation directory.

```bash
docker compose up -d
```

--------------------------------

### Create PandaWiki Installation Directory

Source: https://pandawiki.docs.baizhi.cloud/node/01971602-bb4e-7c90-99df-6d3c38cfd6d5

Manually create a directory to store PandaWiki and its associated data. This is the first step in the manual installation process.

```bash
mkdir /data/pandawiki
```

--------------------------------

### PandaWiki Installation Success Output

Source: https://pandawiki.docs.baizhi.cloud/node/01971602-bb4e-7c90-99df-6d3c38cfd6d5

This is an example of the success message displayed after the PandaWiki installation completes. It provides the access URLs, username, and password for logging into the PandaWiki console.

```text
SUCCESS  控制台信息:
SUCCESS    访问地址(内网): https://*.*.*.*:2443
SUCCESS    访问地址(外网): https://*.*.*.*:2443
SUCCESS    用户名: admin
SUCCESS    密码: **********************
```

--------------------------------

### Example Output of Loaded Images

Source: https://pandawiki.docs.baizhi.cloud/node/019b1176-3f58-7cd5-b93c-71c98c1d9f97

This output indicates the successful loading of various PandaWiki-related Docker images. Each line shows a successfully loaded image with its registry path and tag.

```text
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/anydoc:v0.7.1
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-api:v3.55.0
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-app:v3.55.0
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-caddy:2.10-alpine
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-consumer:v3.55.0
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-minio:RELEASE.2025-04-22T22-12-26Z-cpuv1
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-nats:2.11.3-alpine
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-nginx:v3.55.0
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-postgres:17.5
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-qdrant:v1.14.1
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-raglite:1-5-0
Loaded image: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-redis:7.4.2-alpine
```

--------------------------------

### PandaWiki Default Installation Directory

Source: https://pandawiki.docs.baizhi.cloud/node/019cd681-c632-72a9-92da-795fd0482ff0

This snippet shows the default directory where PandaWiki is installed on the server. It's important for locating configuration files like `.env`.

```bash
/data/pandawiki/
```

--------------------------------

### Download Docker Compose File

Source: https://pandawiki.docs.baizhi.cloud/node/01971602-bb4e-7c90-99df-6d3c38cfd6d5

Download the docker-compose.yml file into your chosen PandaWiki installation directory. This file defines the services and configurations for running PandaWiki with Docker Compose.

```bash
cd /data/pandawiki
wget "https://release.baizhi.cloud/panda-wiki/docker-compose.yml"
```

--------------------------------

### Configure PandaWiki Environment Variables

Source: https://pandawiki.docs.baizhi.cloud/node/01971602-bb4e-7c90-99df-6d3c38cfd6d5

Create a .env file in the installation directory and populate it with necessary configuration variables. Replace {{PASSWORD}} with strong, randomly generated passwords. Ensure ADMIN_PASSWORD is secure and memorable, as it's used for the admin panel login.

```dotenv
# 时区
TIMEZONE=Asia/Shanghai
# 容器网段
SUBNET_PREFIX=169.254.15
# 中间件密码
POSTGRES_PASSWORD={{PASSWORD}}
NATS_PASSWORD={{PASSWORD}}
JWT_SECRET={{PASSWORD}}
S3_SECRET_KEY={{PASSWORD}}
QDRANT_API_KEY={{PASSWORD}}
REDIS_PASSWORD={{PASSWORD}}
# 管理后台登录密码
ADMIN_PASSWORD={{PASSWORD}}
# 管理后台访问端口
ADMIN_PORT=2443
```

--------------------------------

### View PandaWiki Configuration and Passwords

Source: https://pandawiki.docs.baizhi.cloud/node/019cd681-c632-72a9-92da-795fd0482ff0

Access the `.env` file in the PandaWiki installation directory to retrieve sensitive information such as the admin password and database credentials.

```bash
# 如果不是安装在默认目录,同理替换下面的命令
cat /data/pandawiki/.env
```

--------------------------------

### Retrieve Admin Password from .env File

Source: https://pandawiki.docs.baizhi.cloud/node/019cd681-c632-72a9-92da-795fd0482ff0

This example demonstrates how to extract the `ADMIN_PASSWORD` value from the `.env` file, which stores the backend administrator's login password.

```bash
# 管理后台登录密码
ADMIN_PASSWORD=xxxxxx
```

--------------------------------

### 导出 Docker 镜像脚本

Source: https://pandawiki.docs.baizhi.cloud/node/019b1176-3f58-7cd5-b93c-71c98c1d9f97

在具备外网连接的机器上执行此脚本，以自动下载 docker-compose.yml 并导出所有必需的 Docker 镜像为 .tar 文件。

```bash
#!/bin/bash

# 定义 docker-compose 文件名和下载链接
COMPOSE_FILE="docker-compose.yml"
DOWNLOAD_URL="<https://release.baizhi.cloud/panda-wiki/docker-compose.yml>"

# --- 步骤 1: 下载最新的 docker-compose.yml 文件 ---
echo "--- 步骤 1/3: 正在下载最新的 ${COMPOSE_FILE} 文件 ---"
# 使用 curl 下载文件，并检查是否成功
if curl -fsSL -o "${COMPOSE_FILE}" "${DOWNLOAD_URL}"; then
    echo "✅ ${COMPOSE_FILE} 文件下载成功。"
else
    echo "❌ 错误：下载 ${DOWNLOAD_URL} 失败。请检查网络连接和URL是否正确。"
    exit 1
fi
echo "---------------------------------------------------------"

# --- 步骤 2: 执行 docker compose pull 拉取所有镜像 ---
echo "--- 步骤 2/3: 正在执行 docker compose pull 拉取所有镜像 ---"
# 使用下载的 compose 文件拉取所有镜像
if docker compose -f "${COMPOSE_FILE}" pull; then
    echo "✅ 所有镜像拉取成功。"
else
    echo "❌ 错误：docker compose pull 执行失败。请检查 Docker 服务状态。"
    exit 1
fi
echo "---------------------------------------------------------"

# --- 步骤 3: 动态提取并导出所有镜像为 .tar 文件 ---

echo "--- 步骤 3/3: 动态提取并导出所有镜像为 .tar 文件 ---"

# 动态提取所有镜像名称
# 过滤出所有包含 'image:' 的行，并提取冒号后的内容（镜像名称和标签），去除首尾空格。
IMAGES=$(grep 'image:' "${COMPOSE_FILE}" | awk -F 'image:' '{print $2}' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sort -u)

if [ -z "$IMAGES" ]; then
    echo "❌ 警告：未在 ${COMPOSE_FILE} 文件中找到任何镜像定义。脚本停止。"
    exit 1
fi

echo "共找到以下 $(echo "$IMAGES" | wc -l) 个唯一镜像，开始导出..."
echo "---------------------------------------------------------"

# 循环导出每个镜像
for IMAGE in $IMAGES; do
    # 构造文件名：移除仓库地址（如果有），替换斜杠和冒号为下划线，构造安全的文件名
    # 示例: chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-api:v3.55.0 -> panda-wiki-api_v3.55.0.tar
    FILENAME=$(echo "$IMAGE" | sed 's/.*\\///g' | sed 's/:/_/g')
    TAR_FILE="${FILENAME}.tar"
    
    echo "正在导出: ${IMAGE} -> ${TAR_FILE}"
    
    # 执行 docker save 命令
    if docker save -o "${TAR_FILE}" "${IMAGE}"; then
        echo "✅ 成功导出 ${TAR_FILE}"
    else
        # 理论上 pull 成功后 save 不会失败，但仍进行错误处理
        echo "❌ 导出 ${IMAGE} 失败！"
    fi
    
    echo "---"
done

echo "🎉 所有最新镜像已下载并导出完成。文件保存在当前目录。"
```

--------------------------------

### 配置 Ollama 服务监听地址

Source: https://pandawiki.docs.baizhi.cloud/node/019a160d-0528-736a-b88e-32a2d1207f3e

通过编辑 systemd 服务文件，将 OLLAMA_HOST 设置为 0.0.0.0 以允许外部访问。

```bash
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
```

```bash
systemctl daemon-reload
systemctl restart ollama
```

--------------------------------

### 检查容器运行状态

Source: https://pandawiki.docs.baizhi.cloud/node/019cdff6-4252-7739-8958-d164035ad788

使用 docker ps 命令确认各服务容器是否正常运行，重点检查是否存在持续 Restarting 状态的容器。

```bash
docker ps
```

--------------------------------

### Retrieve PostgreSQL Password

Source: https://pandawiki.docs.baizhi.cloud/node/019cfa77-df6a-7d3b-a3b7-d22db5e1f656

Use this command to extract the database password from the .env file in the installation directory.

```bash
# 如果不是默认安装目录，请替换为实际路径
cat /data/pandawiki/.env | grep POSTGRES_PASSWORD
```

```text
# 中间件密码
POSTGRES_PASSWORD=你的数据库密码
```

--------------------------------

### 配置 .env 文件

Source: https://pandawiki.docs.baizhi.cloud/node/019b1176-3f58-7cd5-b93c-71c98c1d9f97

创建并编辑 .env 配置文件，需将 {{PASSWORD}} 替换为随机生成的强密码。

```text
# 时区
TIMEZONE=Asia/Shanghai
# 容器网段
SUBNET_PREFIX=169.254.15
# 中间件密码
POSTGRES_PASSWORD={{PASSWORD}}
NATS_PASSWORD={{PASSWORD}}
JWT_SECRET={{PASSWORD}}
S3_SECRET_KEY={{PASSWORD}}
QDRANT_API_KEY={{PASSWORD}}
REDIS_PASSWORD={{PASSWORD}}
# 管理后台登录密码
ADMIN_PASSWORD={{PASSWORD}}
```

--------------------------------

### PandaWiki Login Information

Source: https://pandawiki.docs.baizhi.cloud/node/01971650-cb16-7957-96fd-26207f49f264

This output provides the access URL, username, and password for logging into the PandaWiki console after installation.

```text
SUCCESS  控制台信息:
SUCCESS    访问地址(内网): http://*.*.*.*:2443
SUCCESS    访问地址(外网): http://*.*.*.*:2443
SUCCESS    用户名: admin
SUCCESS    密码: **********************
```

--------------------------------

### 测试远程网络连通性

Source: https://pandawiki.docs.baizhi.cloud/node/019b4950-9dd9-75dc-b165-5d248df83cf1

在客户端终端测试服务器端口及网络是否可达。

```bash
# 在需要访问PandaWiki的机子终端进行执行
telnet <安装PandaWiki的服务器地址> <配置监听的端口>
ping <安装PandaWiki的内网或外网服务器地址>
```

--------------------------------

### 启动 Xinference 服务

Source: https://pandawiki.docs.baizhi.cloud/node/019a160d-0528-736a-b88e-32a2d1207f3e

在启动 Xinference 时指定监听地址为 0.0.0.0。

```bash
xinference-local -H 0.0.0.0
```

--------------------------------

### Pull a Specific Docker Image

Source: https://pandawiki.docs.baizhi.cloud/node/019cd681-c632-72a9-92da-795fd0482ff0

Use this command to manually pull a single Docker image for testing purposes if the installation script fails. This helps diagnose network or registry access issues.

```bash
docker pull chaitin-registry.cn-hangzhou.cr.aliyuncs.com/chaitin/panda-wiki-minio:RELEASE.2023-09-20T22-49-55Z
```

--------------------------------

### 检查服务端口监听状态

Source: https://pandawiki.docs.baizhi.cloud/node/019b4950-9dd9-75dc-b165-5d248df83cf1

在服务器上验证指定端口是否被正确监听。

```bash
# 在服务器上执行
ss -nltp | grep <配置的端口> 
```

--------------------------------

### Check Container Logs for Import Errors

Source: https://pandawiki.docs.baizhi.cloud/node/019d1df2-611b-7e4c-956a-6cc9787d3c58

Use these commands to monitor the logs of the PandaWiki API and crawler containers, which can help diagnose document import failures. Ensure you have Docker installed and running.

```bash
docker logs -f panda-wiki-api --tail=100
```

```bash
docker logs -f panda-wiki-crawler --tail=100
```

--------------------------------

### 验证模型可用性

Source: https://pandawiki.docs.baizhi.cloud/node/019a160d-0528-736a-b88e-32a2d1207f3e

通过 API 测试对话、向量及重排序模型的功能。

```bash
  curl -X POST \
  http://部署机器的ip:端口/v1/chat/completions \
  -H "Authorization: Bearer 您设置的API Key,没有可以去掉这行" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型列表中您想要配置的模型id",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

```bash
  curl -X POST \
  http://部署机器的ip:端口/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您设置的API Key,没有可以去掉这行" \
  -d '{
    "model": "模型列表中您想要配置的模型id",
    "input": "hello, nice to meet you , and you?",
    "encoding_format": "float"
  }'
```

```bash
  curl -X POST \
  http://部署机器的ip:端口/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 您设置的API Key,没有可以去掉这行" \
  -d '{
    "model": "模型列表中您想要配置的模型id",
    "documents": ["hello"],
	"query": "test"
  }'
```

--------------------------------

### 查看服务容器日志

Source: https://pandawiki.docs.baizhi.cloud/node/019cdff6-4252-7739-8958-d164035ad788

通过 docker logs 命令查看特定服务的运行日志，用于定位接口、文档导入或 AI 问答相关的报错信息。

```bash
# 接口相关日志
docker logs -f panda-wiki-api --tail=100

# 文档导入需要额外查看
docker logs -f panda-wiki-crawler --tail=100

# AI问答/文档学习需要额外查看
docker logs -f panda-wiki-raglite --tail=100
```

--------------------------------

### 上传企业微信校验文件至容器

Source: https://pandawiki.docs.baizhi.cloud/node/0198eac0-567c-7adc-9c4d-f6e775e695ea

将企业微信要求的校验文件上传至 PandaWiki 容器的指定目录。

```bash
docker cp <文件> panda-wiki-app:/app/app/public/
```

--------------------------------

### Configure PandaWiki MCP Server in Cursor

Source: https://pandawiki.docs.baizhi.cloud/node/019aa45c-90c1-7e6f-b17a-74ab1b200153

Paste this configuration into your Cursor `~/.cursor/mcp.json` file to add PandaWiki as a global MCP server. You can also create a `.cursor/mcp.json` file in your project folder for project-specific configuration.

```json
{
    "mcpServers": {
        "pandawiki": {
            "url": "MCP URL",
            "headers": {
                "Authorization": "Bearer 访问口令(没有可不填)"
            }
        }
    }
}
```