Clansty Projects Docs

https://kb.0w.al
Admin
Clansty Projects Docs is a documentation portal that provides various customizable layout and...
Tokens:10,704
Snippets:123
Trust Score:5.4
Update:9 months ago
Show doc for...
Tokens:
Raw
### View Q2TG Logs (Bash)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Monitor the Q2TG service logs in real-time using 'docker compose logs -f q2tg'. This is essential for troubleshooting during setup and operation.

```bash
docker compose logs -f q2tg
```

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

### Configure Existing PostgreSQL Database (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

If you have an existing PostgreSQL instance, you can configure Q2TG to use it by removing the default postgres service from docker-compose and setting the DATABASE_URL environment variable with your connection details.

```yaml
services:
  # Remove this section if using an existing Postgres instance
  postgres:
    image: postgres:14-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: db_name
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - postgresql:/var/lib/postgresql/data

  q2tg:
    environment:
      - DATABASE_URL=postgres://user:password@dbIp/db_name
```

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

### Podman Volume Configuration Adjustment (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

When deploying with Podman, specific volume configurations in the docker-compose file need to be removed, particularly those related to Docker socket access and Q2TG data persistence.

```yaml
    volumes:
      - q2tg:/app/data
      - cache:/app/.config/QQ/NapCat/temp
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
```

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

### Restart Q2TG Service (Bash)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Restart the Q2TG service with the 'docker compose restart q2tg' command. This is useful for applying configuration changes or recovering from issues.

```bash
docker compose restart q2tg
```

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

### Configure Proxy Server Environment Variables (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Optionally, configure proxy server IP and port using PROXY_IP and PROXY_PORT environment variables if Q2TG needs to access Telegram through a proxy.

```yaml
# If no proxy is needed, these variables can be omitted
- PROXY_IP=your_proxy_server_ip
- PROXY_PORT=your_proxy_server_port
```

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

### Configure Docker Compose for Signature Service Restart (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E8%BF%9B%E5%85%A5%E6%95%B0%E6%8D%AE%E5%BA%93%E8%B0%83%E8%AF%95

This YAML configuration snippet enables Q2TG to restart the signature service container by mounting the Docker socket. This is crucial for troubleshooting signature service issues in a Docker deployment.

```yaml
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

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

### Configure Web Endpoint Environment Variable (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Define the WEB_ENDPOINT environment variable in your Docker Compose configuration. This should be the public URL (HTTPS) where Q2TG is accessible, crucial for features like RichHeader.

```yaml
- WEB_ENDPOINT=https://your-domain.com
```

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

### Get Database Container IP Address (Bash)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E8%BF%9B%E5%85%A5%E6%95%B0%E6%8D%AE%E5%BA%93%E8%B0%83%E8%AF%95

This command retrieves the internal IP address of the database container managed by Docker. It requires the container name, typically found using 'docker ps'.

```bash
docker inspect q2tg-postgres-1 | grep IP
```

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

### Modify Cache Directory for Q2TG V4 (Docker Bind Mount)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BB%8E%20V3%20%E6%9B%B4%E6%96%B0%E5%88%B0%20V4

Updates the Docker bind mount volume configuration to redirect the cache directory from './cache' to '/app/.config/QQ/NapCat/temp'. This ensures Q2TG V4 correctly shares the cache directory with NapCat. Adjust the host directory './cache' as per your actual setup.

```yaml
services:
  q2tg:
    volumes:
      # 请根据实际目录调整 ./cache
      - ./cache:/app/.config/QQ/NapCat/temp
```

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

### Configure Telegram Bot Token Environment Variable (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Set the Telegram Bot Token environment variable in your Docker Compose file. This token is generated by BotFather after creating a new Telegram bot.

```yaml
- TG_BOT_TOKEN=YOUR_BOT_TOKEN
```

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

### Configure Telegram API Environment Variables (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Set the necessary environment variables for Telegram API ID and API Hash within your Docker Compose configuration. These are obtained from the Telegram My Telegram Core application.

```yaml
- TG_API_ID=YOUR_API_ID
- TG_API_HASH=YOUR_API_HASH
```

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

### Configure Telegram WebAPP Environment Variable (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2

Set the CRV_VIEWER_APP environment variable to the link generated by BotFather for your Telegram WebApp. This enhances the user experience for features like merged forward viewers.

```yaml
- CRV_VIEWER_APP=https://t.me/your_bot_username/your_app_name
```

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

### 配置不支持多人共用的签名服务器 (Docker Compose)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%A4%9A%E5%AE%9E%E4%BE%8B%E6%A8%A1%E5%BC%8F%E4%BB%8B%E7%BB%8D

当签名服务器不支持多人共用时，需要修改 docker-compose.yaml 文件以运行多个独立的签名实例。每个实例使用相同的镜像但配置不同的 BASE_PATH 环境变量。此配置移除了 SIGN_API 和 SIGN_VER 环境变量，需要在数据库中手动添加签名 API 设置。

```yaml
services:
  sign1:
    image: xzhouqd/qsign:core-1.1.9
    restart: unless-stopped
    stop_signal: SIGKILL
    environment:
      - BASE_PATH=/srv/qsign/qsign/txlib/8.9.71
    networks: 
      - default
  sign2: 
    image: xzhouqd/qsign:core-1.1.9
    restart: unless-stopped
    stop_signal: SIGKILL
    environment: 
      - BASE_PATH=/srv/qsign/qsign/txlib/8.9.71
    networks: 
      - default
      
  q2tg:
    image: ghcr.io/clansty/q2tg:rainbowcat
    depends_on:
      - sign1
      - sign2
......
```

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

### 启动 Q2TG (Docker Compose)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%20Nginx%20%E5%81%9A%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86

使用 Docker Compose 命令启动 Q2TG 服务。此命令将在后台运行容器。

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

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

### 配置 NapCat 容器

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%E4%B8%8D%E5%90%8C%20QQ%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E7%9A%84%E5%AE%B9%E5%99%A8%E9%83%A8%E7%BD%B2%E6%96%B9%E5%BC%8F/%E4%BD%BF%E7%94%A8%20NapCat%20%E5%8D%95%E5%AE%9E%E4%BE%8B%E9%83%A8%E7%BD%B2

这是使用 NapCat 作为 QQ 客户端的 Docker Compose 配置示例。它定义了 NapCat 服务，包括镜像、环境变量、端口映射、MAC 地址、重启策略和卷挂载。请务必修改 ACCOUNT 和 mac_address。

```yaml
volumes:
  napcat-data2:
  napcat-config2:

services:
  napcat2:
    image: mlikiowa/napcat-docker:latest
    environment:
      - ACCOUNT=要登录的 QQ 号
    ports:
      - 6098:6099
    mac_address: 02:42:12:34:56:78 # 请修改为一个固定的 MAC 地址，但是不要和其他容器或你的主机重复
    restart: unless-stopped
    volumes:
      - napcat-data2:/app/.config/QQ
      - napcat-config2:/usr/src/app/napcat/config
      - cache:/app/.config/QQ/NapCat/temp

  q2tg:
    depends_on:
      - napcat2
```

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

### 将 icqq 实例转换为 NapCat

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%E4%B8%8D%E5%90%8C%20QQ%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E7%9A%84%E5%AE%B9%E5%99%A8%E9%83%A8%E7%BD%B2%E6%96%B9%E5%BC%8F/%E4%BD%BF%E7%94%A8%20NapCat%20%E5%8D%95%E5%AE%9E%E4%BE%8B%E9%83%A8%E7%BD%B2

这部分描述了如何将现有的使用 icqq 的实例迁移到 NapCat。这包括从 Docker Compose 中删除 sign 容器，添加 NapCat 容器，以及修改 Q2TG 数据库中的 bot 类型和 wsUrl。

```sql
-- 在 QqBot 表中将对应的 bot 的 type 改为 napcat
UPDATE QqBot SET type = 'napcat' WHERE bot_id = 'your_bot_id';

-- 在 QqBot 表中设置 wsUrl
UPDATE QqBot SET wsUrl = 'ws://napcat:3001' WHERE bot_id = 'your_bot_id';
```

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

### 重启 Nginx 容器 (Docker Compose)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%20Nginx%20%E5%81%9A%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86

重启 Nginx 容器以应用 Nginx 配置更改。此命令将重新加载 Nginx。

```bash
docker compose restart nginx
```

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

### Configure Signing Server Version (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%E4%B8%8D%E5%90%8C%20QQ%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E7%9A%84%E5%AE%B9%E5%99%A8%E9%83%A8%E7%BD%B2%E6%96%B9%E5%BC%8F/%E4%BD%BF%E7%94%A8%20icqq%20%E5%8D%95%E5%AE%9E%E4%BE%8B%E9%83%A8%E7%BD%B2

Defines the signing server version used by icqq. Ensure the version in `BASE_PATH` and `SIGN_VER` environment variables are synchronized. Refer to the qsign Docker Hub page for supported versions.

```yaml
environment:
  # 需要与下方的 SIGN_VER 同步
  # 配置请参考 https://hub.docker.com/r/xzhouqd/qsign
  - BASE_PATH=/srv/qsign/qsign/txlib/8.9.71
```

```yaml
environment:
  - SIGN_VER=8.9.71 # 与上方 sign 容器的配置同步
```

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

### 查看 Nginx 日志 (Docker Compose)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%20Nginx%20%E5%81%9A%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86

查看 Nginx 容器的日志以排查配置问题或监控服务状态。这对于调试反向代理和 SSL 配置非常有用。

```bash
docker compose logs nginx
```

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

### 检查 Certbot SSL 证书状态 (Docker Compose)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%20Nginx%20%E5%81%9A%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86

检查 Certbot 容器的日志以确认是否成功获取 SSL 证书。如果证书获取失败，需要排查 Certbot 配置和域名解析问题。

```bash
docker compose logs certbot
```

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

### 配置 Certbot 邮箱和域名 (Docker Compose)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%20Nginx%20%E5%81%9A%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86

在 Docker Compose 文件中配置 Certbot 以获取 SSL 证书。需要填写您的邮箱和域名，并确保域名已正确解析到服务器 IP。

```yaml
    command: certonly --webroot -w /var/www/certbot --force-renewal --email 你的邮箱 -d 你的域名 --agree-tos
```

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

### 解决 UserBot 登录卡死问题 (GramJS)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98

当 UserBot 在登录时出现卡死现象，通常与 Telegram 的数据中心（DC）有关。通过设置环境变量 `TG_INITIAL_DCID` 和 `TG_INITIAL_SERVER`，可以指定 UserBot 连接到特定的数据中心，从而解决登录卡死问题。此方法适用于使用 GramJS 库的场景。

```yaml
      - TG_INITIAL_DCID=5 
      - TG_INITIAL_SERVER=91.108.56.174
```

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

### Using a Custom Signing Server (YAML)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%E4%B8%8D%E5%90%8C%20QQ%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E7%9A%84%E5%AE%B9%E5%99%A8%E9%83%A8%E7%BD%B2%E6%96%B9%E5%BC%8F/%E4%BD%BF%E7%94%A8%20icqq%20%E5%8D%95%E5%AE%9E%E4%BE%8B%E9%83%A8%E7%BD%B2

Configures icqq to use a custom signing server. Remove the default `sign` container and update the `SIGN_API` and `SIGN_VER` environment variables in the `q2tg` service with your server's address and version.

```yaml
  sign:
    image: xzhouqd/qsign:core-1.1.9
    restart: unless-stopped
    environment:
      # 需要与下方的 SIGN_VER 同步
      # 配置请参考 https://hub.docker.com/r/xzhouqd/qsign
      - BASE_PATH=/srv/qsign/qsign/txlib/8.9.71
```

```yaml
  q2tg:
    image: ghcr.io/clansty/q2tg:rainbowcat
    restart: unless-stopped
    depends_on:
      - postgres
      - sign
```

```yaml
      - SIGN_API=http://sign:8080/sign?key=114514
      - SIGN_VER=8.9.71 # 与上方 sign 容器的配置同步
```

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

### Modify Cache Directory for Q2TG V4 (Docker Named Volume)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BB%8E%20V3%20%E6%9B%B4%E6%96%B0%E5%88%B0%20V4

Configures Docker's named volumes for Q2TG V4, specifically mapping a 'cache' volume to '/app/.config/QQ/NapCat/temp'. This method is suitable if you prefer using Docker-managed volumes. This configuration is essential for Q2TG's internal caching, regardless of NapCat usage.

```yaml
volumes:
  postgresql:
  q2tg:
  cache:

services:
  q2tg:
    volumes:
      # 请根据实际目录调整 ./cache
      - cache:/app/.config/QQ/NapCat/temp
```

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

### Update Q2TG Docker Image Version

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BB%8E%20V3%20%E6%9B%B4%E6%96%B0%E5%88%B0%20V4

Demonstrates how to update the Q2TG Docker image from the 'rainbowcat' tag (V3) to the 'sleepyfox' tag (V4). This change is necessary to use the latest version of Q2TG. Ensure you are pulling the correct image from GitHub Container Registry.

```yaml
services:
  q2tg:
    image: ghcr.io/clansty/q2tg:rainbowcat
    image: ghcr.io/clansty/q2tg:sleepyfox
```

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

### 配置 Nginx SSL 反向代理 (Nginx)

Source: https://kb.0w.al/%E6%96%87%E6%A1%A3/Q2TG/%E4%BD%BF%E7%94%A8%20Nginx%20%E5%81%9A%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86

配置 Nginx 以启用 SSL 并将请求反向代理到 Q2TG 服务。需要取消注释 SSL 相关配置块，并替换占位符为您的域名和证书路径。

```nginx
    # server {
    #     listen 443 ssl;
    #     listen [::]:443 ssl;
    #     server_name 你的域名;
    #     ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem;
    #     ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem;

    #     location / {
    #         proxy_pass http://q2tg:8080;
    #     }
    # }

```
Tokens:
Raw