yuanzhe1999/wechat-selkies

Fork 0

mirror of https://github.com/nickrunning/wechat-selkies.git synced 2026-05-09 00:24:09 +00:00

Files

Nick007 63b3f34527 feat: extract docker-compose config to .env and update commands to docker compose

2026-03-23 19:39:28 +08:00

13 KiB

Raw Blame History

WeChat Selkies

English | 中文

Docker-based WeChat/QQ Linux client with browser access support using Selkies WebRTC technology.

Project Overview

This project packages the official WeChat/QQ Linux client in a Docker container, enabling direct WeChat/QQ usage in browsers through Selkies technology without local installation. Suitable for server deployment, remote work, and other scenarios.

Upgrade Notes

If some features are missing after an upgrade, please clear the openbox directory in the local mounted directory (e.g., ./config/.config/openbox).

Features

🌐 Browser Access: Use WeChat directly through web browsers without local installation
🐳 Dockerized Deployment: Simple containerized deployment with environment isolation
🔒 Data Persistence: Supports persistent storage of configurations and chat records
🎨 Chinese Support: Complete Chinese fonts and localization support, including local Chinese input methods
🖼️ Image Copy: Support image copying through sidebar panel
📁 File Transfer: Support file transfer through sidebar panel
🖥️ AMD64 and ARM64 Architecture Support: Compatible with mainstream CPU architectures
🔧 Hardware Acceleration: Optional GPU hardware acceleration support
🪟 Window Switcher: Added a floating window switcher in the top left corner for easy switching to background windows, laying the foundation for adding other features in the future
🤖 Auto Start: Configurable auto-start for WeChat and QQ clients (optional)
📋 Desktop Shortcut Integration: Automatically scans .desktop files in ~/Desktop/ and adds them to the right-click menu, making it easy to launch third-party applications (e.g., apps installed via proot-apps)
📂 File Manager: Built-in PCManFM lightweight file manager, accessible from the right-click menu for easy file management inside the container

Screenshots

Quick Start

Requirements

Docker
Docker Compose
Modern browser with WebRTC support (Chrome, Firefox, Safari, etc.)

Quick Deployment

Direct deployment using pre-built images GitHub Container Registry image:

docker run -it -p 3001:3001 -v ./config:/config --device /dev/dri:/dev/dri ghcr.io/nickrunning/wechat-selkies:latest

Docker Hub image:

docker run -it -p 3001:3001 -v ./config:/config --device /dev/dri:/dev/dri nickrunning/wechat-selkies:latest

Access WeChat

Open in browser: https://localhost:3001 or https://<server-ip>:3001

Note

: 3001 port is for HTTPS access. If you need HTTP access, please map port 3000 as well.

Docker Compose Deployment

Create project directory and navigate into it
```
mkdir wechat-selkies
cd wechat-selkies
```

Create docker-compose.yml file with the following content

 services:
   wechat-selkies:
     image: nickrunning/wechat-selkies:latest    # or ghcr.io/nickrunning/wechat-selkies:latest
     container_name: wechat-selkies
     ports:
       - "${HTTP_PORT:-3000}:3000"
       - "${HTTPS_PORT:-3001}:3001"
     restart: unless-stopped
     volumes:
       - ./config:/config
     devices:
       - /dev/dri:/dev/dri
     environment:
       - PUID=${PUID:-1000}
       - PGID=${PGID:-100}
       - TZ=Asia/Shanghai
       - LC_ALL=zh_CN.UTF-8
       - AUTO_START_WECHAT=true
       - AUTO_START_QQ=false
       - CUSTOM_USER=${CUSTOM_USER:-}
       - PASSWORD=${PASSWORD:-}
     shm_size: "${SHM_SIZE:-1gb}"

Create .env file (optional)

Copy .env.example and modify as needed. Variables not set will use default values:
```
cp .env.example .env
```
.env file example:
```
HTTP_PORT=3000
HTTPS_PORT=3001
PUID=1000
PGID=100
# CUSTOM_USER=
# PASSWORD=
SHM_SIZE=1gb
```
Start the service
```
docker compose up -d
```

Source Code Deployment

Clone the repository

git clone https://github.com/nickrunning/wechat-selkies.git
cd wechat-selkies

Start the service
```
docker compose up -d
```
Access WeChat

Open in browser: https://localhost:3001 or https://<server-ip>:3001

Configuration

For more custom configurations, please refer to Selkies Base Images from LinuxServer.

Docker Hub Push Configuration

This project supports pushing to both GitHub Container Registry and Docker Hub. Docker Hub push is optional and requires manual configuration. Please add the following Environment Secrets and Environment Variables in your repository to enable Docker Hub push functionality:

Environment Secrets:

DOCKERHUB_USERNAME: Your Docker Hub username
DOCKERHUB_TOKEN: Your Docker Hub Access Token

Environment Variables:

ENABLE_DOCKERHUB: Set to true to enable Docker Hub push

Environment Variables

Configure the following environment variables in docker-compose.yml. Variables with ${VAR:-default} syntax can be overridden via a .env file:

Variable	Default	Description
`TITLE`	`WeChat Selkies`	Web UI title
`PUID`	`1000`	User ID
`PGID`	`100`	Group ID
`TZ`	`Asia/Shanghai`	Timezone setting
`LC_ALL`	`zh_CN.UTF-8`	Locale setting
`CUSTOM_USER`	-	Custom username (recommended)
`PASSWORD`	-	Web UI access password (recommended)
`AUTO_START_WECHAT`	`true`	Whether to automatically start the WeChat client
`AUTO_START_QQ`	`false`	Whether to automatically start the QQ client

Port Configuration

3001: Web UI access port

Volume Mounts

./config:/config: WeChat configuration and data persistence directory

Note: If the right-click menu lacks WeChat related options after an upgrade, please clear the openbox directory in the local mounted directory (e.g., ./config/.config/openbox).

Installing Third-Party Applications (e.g., Telegram)

This project supports installing third-party Linux applications via proot-apps. Here's how to install Telegram as an example:

Open the container desktop in your browser
Click the Sidebar on the left → Applications
Find Telegram in the application list
Click the Install button and wait for the installation to complete

Once installed, the application shortcut will automatically appear in the ~/Desktop/ directory, and the right-click menu will auto-refresh — no container restart needed to launch the app from the menu.

Tip: To uninstall an application, go to Sidebar → Applications, select the app, and click Uninstall. The right-click menu will update automatically.

Advanced Configuration

Hardware Acceleration

If your system supports GPU hardware acceleration, the Docker Compose configuration includes relevant device mapping:

devices:
  - /dev/dri:/dev/dri

Directory Structure

wechat-selkies/
├── docker-compose.yml          # Docker Compose configuration file
├── .env.example                # Environment variables example file
├── Dockerfile                  # Docker image build file
├── LICENSE                     # License
├── README.md                   # Project documentation (Chinese)
├── README_en.md                # Project documentation (English)
├── config/                     # Configuration and data persistence directory
└── root/                       # Container initialization files
    ├── defaults/
    │   └── autostart           # Auto-start configuration
    └── wechat.png              # WeChat icon

Troubleshooting

Updating WeChat/QQ Version

When WeChat or QQ displays a "version outdated" message, simply pull the latest image and recreate the container. Your chat history and configurations will be preserved:

# Using pre-built images
docker compose pull && docker compose up -d

# Using source code build
git pull && docker compose up -d --build

Note: The WeChat and QQ download URLs point to the latest official versions. Rebuilding the image will automatically download the newest version.

Common Issues

Unable to access Web UI
- Check if port 3001 is occupied
- Confirm Docker container is running normally: docker ps

Log Viewing

View container runtime logs:

docker compose logs -f wechat-selkies

Technical Architecture

Base Image: ghcr.io/linuxserver/baseimage-selkies:ubuntunoble
WeChat Client: Official WeChat Linux version
Web Technology: Selkies WebRTC
Containerization: Docker + Docker Compose

Contributing

Issues and Pull Requests are welcome!

Fork this project
Create feature branch: git checkout -b feature/your-feature
Commit changes: git commit -am 'Add some feature'
Push branch: git push origin feature/your-feature
Submit Pull Request

License

This project is licensed under MIT License. See the LICENSE file for details.

📜 License Statement

Project License: MIT License - A permissive open source license
Dependency Note: This project uses LinuxServer.io baseimage-selkies as base image
License Compatibility: Since this project only uses the base image without modifying its source code, following containerized software licensing practices, it can adopt the MIT license
Open Source: Complete project source code is publicly available on GitHub: https://github.com/nickrunning/wechat-selkies

Disclaimer and Copyright Notice

🚨 Important Statement

This project has no affiliation with Tencent and is an independent third-party open source project.

📋 Copyright Notice

WeChat® is a registered trademark and copyrighted work of Tencent
The copyright of WeChat-related icons, logos and other visual elements used in this project belongs to Tencent
This project is for technical demonstration and learning purposes only, not for commercial use
In case of copyright disputes, relevant content will be removed immediately

⚖️ Legal Compliance

This project strictly complies with relevant laws, regulations and user agreements
Users should comply with local laws and regulations when using this project
This project assumes no legal responsibility for users' actions
If Tencent believes there is infringement, please contact us for immediate resolution

🎯 Terms of Use

This project is for learning, research and personal use only
Prohibited for any commercial purposes or profit-making activities
Users should bear the risks and legal responsibilities of use
Please comply with WeChat user agreements and related terms of service

13 KiB Raw Blame History