# ai-goofish-monitor: theo dõi đồ cũ Xianyu bằng AI — hướng dẫn cài đặt và dùng

> ai-goofish-monitor là ứng dụng mã nguồn mở viết bằng Python, tự động tìm kiếm trên Xianyu (Goofish), để AI phân tích từng sản phẩm rồi báo cho bạn món phù hợp. Có giao diện web để tạo tác vụ, quản lý tài khoản và xem kết quả. Cài bằng Docker khá gọn, nhưng bạn cần tài khoản Xianyu và một API key của mô hình AI hỗ trợ đọc ảnh.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-17 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/ai-goofish-monitor-theo-doi-xianyu-bang-ai-huong-dan-cai-dat-2

ai-goofish-monitor là một hệ thống theo dõi chợ đồ cũ Xianyu (闲鱼, còn gọi là Goofish, sàn mua bán đồ cũ lớn của Trung Quốc). Bạn khai báo từ khoá, khoảng giá, khu vực. Hệ thống dùng Playwright (công cụ điều khiển trình duyệt tự động) để tìm hàng mới, rồi nhờ AI xem ảnh và mô tả để quyết định món nào đáng quan tâm. Món phù hợp sẽ được gửi thông báo cho bạn.

Repo này dành cho người hay săn hàng cũ ở Xianyu: dân order hàng, người mua đồ công nghệ, người sưu tầm, hoặc dev muốn có sẵn một hệ thống theo dõi để học hỏi. Thay vì mở app mỗi ngày, lướt hàng trăm tin rồi tự lọc, bạn để máy làm việc đó. Repo hiện có khoảng 19.837 sao và 3.213 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất là bạn không phải viết code. Mọi thứ nằm trong một giao diện web: tạo tác vụ, gắn tài khoản, xem log, xem kết quả. Bạn thậm chí chỉ cần mô tả nhu cầu bằng tiếng tự nhiên, AI sẽ tự sinh tiêu chí đánh giá. Cách cài khuyến nghị là Docker, chỉ vài lệnh.

```repo
- repo | Usagi-org/ai-goofish-monitor
- kind | Ứng dụng
- desc | Hệ thống theo dõi chợ đồ cũ Xianyu (Goofish) bằng Playwright và AI, có giao diện web quản lý nhiều tác vụ, lọc món đáng mua và gửi thông báo tức thì.
- stars | 20k
- lang | Python
- license | MIT
```

## ai-goofish-monitor làm được gì

### Quản lý mọi thứ qua giao diện web

Bạn có trang riêng để quản lý tác vụ, tài khoản Xianyu, chỉnh tiêu chí AI (prompt), xem log chạy và duyệt kết quả. Người không rành lập trình vẫn dùng được, vì không phải sửa file cấu hình thủ công cho từng việc.

### Tạo tác vụ bằng ngôn ngữ tự nhiên

Ở chế độ `AI判断` (AI phán đoán), bạn điền phần «yêu cầu chi tiết» bằng lời thường. Hệ thống chạy nền để sinh ra tiêu chí phân tích, đồng thời hiện một cửa sổ tiến trình riêng. Nếu muốn nhanh và rẻ, có chế độ `关键词判断` (lọc theo từ khoá): chỉ cần điền quy tắc từ khoá, tác vụ tạo ngay và không qua AI.

### Nhiều tác vụ chạy song song

Mỗi tác vụ có từ khoá, mức giá, bộ lọc và prompt AI riêng. Bạn có thể theo dõi máy ảnh cũ ở một tác vụ, laptop ở tác vụ khác, mỗi cái một tiêu chí.

### Lọc nâng cao

Có thể lọc theo miễn phí vận chuyển, khoảng thời gian đăng mới, và khu vực ba cấp tỉnh / thành / quận. README lưu ý: lọc khu vực làm kết quả giảm mạnh, nên mặc định để trống. Chỉ dùng khi bạn thật sự chỉ muốn xem một vùng.

### Thông báo đa kênh

Hỗ trợ ntfy.sh, WeCom (企业微信), Bark, Telegram, Gotify và Webhook. Bạn chọn kênh nào tiện nhất để nhận tin khi có món AI đánh giá là phù hợp.

### Lên lịch, xoay tài khoản và proxy

Tác vụ có thể chạy theo lịch Cron. Hệ thống hỗ trợ nhiều tài khoản, gắn tài khoản cho từng tác vụ, xoay vòng proxy và thử lại khi lỗi. Khi gặp kiểm soát rủi ro (風控) hoặc lỗi, nó đổi tài khoản/proxy rồi chạy lại.

### Lưu trữ gọn

Dữ liệu chính (tác vụ, kết quả, lịch sử giá) nằm trong SQLite, mặc định tại `data/app.sqlite3`. Bạn không phải lo một đống file rời rạc.

## Cần chuẩn bị gì

Theo README, bạn cần:

- **Docker và Docker Compose** nếu cài theo cách khuyến nghị. Image đã có sẵn Chromium, nên máy bạn không phải cài thêm trình duyệt.
- **API của một mô hình AI tương thích OpenAI**, gồm ba thứ: `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL_NAME`. Mô hình phải **hỗ trợ đầu vào là hình ảnh**, vì hệ thống cho AI xem ảnh sản phẩm.
- **Tài khoản Xianyu** đã đăng nhập, để xuất «trạng thái đăng nhập» (login state) dưới dạng JSON bằng tiện ích Chrome mà README giới thiệu, tên là Xianyu Login State Extractor.
- Trình duyệt Chrome trên máy để cài tiện ích đó.

Nếu chọn chạy trực tiếp không dùng Docker (dành cho dev), README yêu cầu thêm: Python 3.10 trở lên, Node.js kèm npm (tác giả đã thử với Node v20.18.3), Playwright CLI cùng Chromium, và Chrome hoặc Edge.

Về phần cứng, GPU hay cấu hình tối thiểu: README không nói gì. Phần AI chạy qua API bên ngoài nên máy bạn không phải gánh mô hình, nhưng đây là suy luận từ cách cấu hình chứ README không khẳng định.

```note
API key AI thường tính phí theo lượng dùng. Mỗi sản phẩm được phân tích kèm ảnh, nên nếu bạn chạy nhiều tác vụ, chi phí có thể tăng. Hãy thử với một tác vụ nhỏ trước và xem bảng giá nhà cung cấp.
```

## Cài đặt từng bước

```steps
- Tải mã nguồn | Clone repo về máy và vào thư mục dự án
- Tạo file cấu hình | Sao chép .env.example thành .env rồi điền key AI
- Chạy bằng Docker | Dùng docker compose up -d để khởi động
- Mở giao diện web | Vào địa chỉ mặc định và đăng nhập
- Thêm tài khoản Xianyu | Dán JSON đăng nhập xuất từ tiện ích Chrome
```

### Tải mã nguồn

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) tại thư mục bạn muốn đặt dự án. Cần cài sẵn Git và Docker.

```bash
git clone https://github.com/Usagi-org/ai-goofish-monitor && cd ai-goofish-monitor
```

Lệnh này tải repo về rồi vào thư mục `ai-goofish-monitor`. Các lệnh tiếp theo phải chạy trong thư mục này.

### Tạo file .env và điền thông tin

```bash
cp .env.example .env
vim .env # 填写相关配置项
```

Lệnh đầu sao chép file mẫu thành `.env`. Lệnh thứ hai là cách README mở file để sửa bằng trình soạn thảo vim. Nếu bạn không quen vim, cứ mở file `.env` bằng bất kỳ trình soạn thảo văn bản nào (Notepad, VS Code…). Trên Windows PowerShell, lệnh `cp` thường dùng được, nhưng bạn cũng có thể tự copy file bằng File Explorer.

Cấu hình tối thiểu theo README:

| Biến | Ý nghĩa | Bắt buộc |
|---|---|---|
| `OPENAI_API_KEY` | API key của mô hình AI | Có |
| `OPENAI_BASE_URL` | Địa chỉ API tương thích OpenAI | Có |
| `OPENAI_MODEL_NAME` | Tên mô hình hỗ trợ ảnh | Có |
| `WEB_USERNAME` / `WEB_PASSWORD` | Tài khoản đăng nhập web, mặc định `admin/admin123` | Không |

Chỗ người mới hay vấp: điền sai `OPENAI_BASE_URL` hoặc chọn mô hình không đọc được ảnh. Hãy lấy thông tin này từ trang của nhà cung cấp AI bạn dùng. Ngoài ra, mật khẩu mặc định `admin123` ai cũng biết, nên hãy đổi nếu bạn mở dịch vụ ra ngoài mạng nội bộ.

### Khởi động bằng Docker

```bash
docker compose up -d
docker compose logs -f app
docker compose down
```

- `docker compose up -d` chạy dịch vụ ở chế độ nền.
- `docker compose logs -f app` xem log trực tiếp (thoát bằng Ctrl+C).
- `docker compose down` dừng và gỡ container khi bạn không dùng nữa.

Nếu tải image chậm hoặc không vào được, README gợi ý dùng bản mirror tăng tốc:

```bash
docker pull ghcr.nju.edu.cn/usagi-org/ai-goofish:latest
docker tag ghcr.nju.edu.cn/usagi-org/ai-goofish:latest ghcr.io/usagi-org/ai-goofish:latest
docker compose up -d
```

Sau này muốn cập nhật phiên bản mới:

```bash
docker compose pull && docker compose up -d
```

Nếu bạn đổi `SERVER_PORT` trong `.env`, nhớ sửa cả phần ánh xạ cổng trong `docker-compose.yaml` cho khớp.

### Đăng nhập và thêm tài khoản Xianyu

Mở `http://127.0.0.1:8000` trong trình duyệt và đăng nhập (mặc định `admin/admin123` nếu bạn chưa đổi). Sau đó:

1. Vào mục «闲鱼账号管理» (quản lý tài khoản Xianyu).
2. Cài tiện ích Chrome Xianyu Login State Extractor, đăng nhập Xianyu trong trình duyệt, xuất JSON trạng thái đăng nhập rồi dán vào ô tương ứng.
3. File đăng nhập được lưu vào thư mục `state/`, ví dụ `state/acc_1.json`.
4. Quay lại «任务管理» (quản lý tác vụ), tạo tác vụ và gắn tài khoản là chạy được.

Giao diện hiện bằng tiếng Trung, nên bạn có thể cần bật dịch trang của trình duyệt.

### Cách chạy không dùng Docker (dành cho dev)

README có hai đường. Đường nhanh là script `start.sh`:

```bash
git clone https://github.com/Usagi-org/ai-goofish-monitor
cd ai-goofish-monitor
cp .env.example .env
chmod +x start.sh
./start.sh
```

Script sẽ kiểm tra Playwright CLI và trình duyệt. Nếu đủ điều kiện, nó tự cài dependency, build giao diện, rồi chạy backend. Trước đó README khuyên chạy:

```bash
python3 -m pip install playwright && python3 -m playwright install chromium
```

`start.sh` là script shell. README không hướng dẫn riêng cho Windows, nên nếu bạn dùng Windows, Docker là lựa chọn ít rủi ro hơn.

Đường thủ công (backend và frontend chạy riêng):

```bash
# 后端
python -m src.app
# 或
uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload

# 前端
cd web-ui
npm install
npm run dev
```

## Kiểm tra đã chạy được chưa

Nếu cài bằng Docker, chạy `docker compose logs -f app` để xem log có báo lỗi khi khởi động không. README không nêu dòng log cụ thể nào là «thành công», nên tiêu chí thực tế là:

- Mở `http://127.0.0.1:8000` thấy trang đăng nhập và đăng nhập được.
- Trong mục tài khoản, dán JSON đăng nhập xong thì file xuất hiện trong thư mục `state/` (ví dụ `state/acc_1.json`).
- Tạo một tác vụ thử, bấm chạy, rồi xem trang nhật ký (log) của tác vụ đó. Trang này hiển thị quá trình chạy và cũng là nơi lộ ra các vấn đề như đăng nhập hết hạn, bị kiểm soát rủi ro hoặc lỗi gọi AI.

Nếu chạy local bằng `./start.sh`, script sẽ in địa chỉ truy cập `http://localhost:8000` và trang tài liệu API tại `http://localhost:8000/docs`.

## Dùng vào việc thật

### Người mua đồ công nghệ cũ săn máy ảnh giá tốt

Bối cảnh: bạn muốn mua một chiếc máy ảnh cũ từ Xianyu nhưng không có thời gian lướt cả ngày. Bạn tạo tác vụ ở chế độ AI, nhập từ khoá là tên dòng máy, đặt khoảng giá, và ở phần «yêu cầu chi tiết» viết bằng lời thường: ví dụ chỉ muốn máy còn bảo hành, ngoại hình đẹp, người bán có uy tín. Hệ thống sinh tiêu chí phân tích, rồi khi có tin mới, AI xem ảnh và mô tả để đánh giá. Kết quả: bạn nhận thông báo chỉ với những tin AI cho là đáng xem, còn lại được lưu vào SQLite để tra lại.

> Mỗi sáng bạn không phải lướt lại hàng trăm tin nữa, chỉ cần mở món mà AI đã chọn sẵn.
>
> — Ông T

### Chủ shop theo dõi giá để nhập hàng

Bối cảnh: bạn bán lại đồ cũ và muốn biết mặt bằng giá một mặt hàng đang biến động ra sao. Bạn tạo tác vụ theo kiểu `关键词判断` với từ khoá và khoảng giá cố định, không qua AI nên nhanh và không tốn tiền AI. Dữ liệu lịch sử giá được lưu lại. Kết quả: bạn có cái nhìn tổng thể thị trường trước khi quyết định nhập. README gợi ý nếu mới kiểm tra thị trường nói chung thì chưa nên bật lọc khu vực, vì nó thu hẹp kết quả rất mạnh.

### Nhận thông báo qua điện thoại

Bối cảnh: bạn không muốn cứ mở trang web để kiểm tra. Hãy điền biến thông báo trong `.env` theo kênh bạn dùng, ví dụ `TELEGRAM_BOT_TOKEN` và `TELEGRAM_CHAT_ID` cho Telegram, `BARK_URL` cho Bark trên iPhone, hoặc `NTFY_TOPIC_URL` cho ntfy. Kết hợp với lịch Cron, hệ thống chạy định kỳ và gửi thẳng tin vào điện thoại khi có món AI cho là phù hợp. Giá trị cụ thể của từng biến bạn xem ở file `.env.example` và tài liệu của dịch vụ thông báo đó.

### Dev dùng làm nền để học hoặc tuỳ biến

Bối cảnh: bạn là lập trình viên mới, muốn xem một hệ thống thật kết hợp trình duyệt tự động, FastAPI, giao diện web và gọi mô hình AI. Repo có sẵn thư mục `src/`, `web-ui/`, `tests/` và tài liệu API: `POST /api/tasks/generate` để tạo tác vụ, `GET /api/tasks/generate-jobs/{job_id}` để theo dõi tiến độ. Bạn có thể chạy bộ kiểm thử bằng lệnh của README:

```bash
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
cd web-ui && npm run build
```

## Lỗi hay gặp và cách xử lý

### Mở trang lên báo thiếu bản build giao diện

Chạy local mà trang báo không có sản phẩm build, nghĩa là thư mục `dist/` ở gốc repo bị thiếu. Cách sửa theo README: chạy `./start.sh`, hoặc vào `web-ui/` chạy `npm run build` rồi chắc chắn kết quả đã được chép vào `dist/` ở gốc repo. Dùng Docker thì thường không gặp lỗi này.

### `./start.sh` báo thiếu Playwright hoặc trình duyệt

Đây là bước kiểm tra điều kiện của script. Hãy cài Playwright CLI và Chromium bằng lệnh `python3 -m pip install playwright && python3 -m playwright install chromium`, đảm bảo máy có Chrome hoặc Edge (Linux có thể dùng Chromium), rồi chạy lại.

### Đăng nhập Xianyu hết hạn hoặc bị kiểm soát rủi ro

Đây là loại lỗi rất dễ gặp với công cụ tự động truy cập một sàn thương mại. README nói trang log giúp bạn chẩn đoán đăng nhập hết hạn, kiểm soát rủi ro và lỗi AI. Hãy xuất lại JSON đăng nhập và cập nhật trong mục quản lý tài khoản. Đừng đặt tần suất quá dày, vì README cảnh báo yêu cầu quá thường xuyên có thể khiến tài khoản bị hạn chế.

### Tạo tác vụ AI không xong ngay

Đó là cách hoạt động bình thường: AI tạo tiêu chí phân tích trước rồi mới tạo tác vụ, chạy như một job nền với cửa sổ tiến trình riêng. Bạn cứ chờ cửa sổ này hoàn tất. Nếu cần nhanh, dùng chế độ từ khoá.

### Đổi cổng nhưng không vào được

Nếu bạn sửa `SERVER_PORT` trong `.env` mà quên chỉnh phần ánh xạ cổng trong `docker-compose.yaml`, trang sẽ không mở được. Sửa cho hai nơi khớp nhau rồi chạy lại `docker compose up -d`.

## Có nên dùng không

**Điểm mạnh:** giao diện web đầy đủ, cài Docker gọn, có sẵn Chromium trong image; hỗ trợ nhiều tác vụ, nhiều kênh thông báo, lịch Cron, xoay tài khoản và proxy; kết hợp AI xem cả ảnh. Giấy phép MIT và cộng đồng lớn.

**Giới hạn:** công cụ xoay quanh Xianyu, và giao diện cùng tài liệu chủ yếu bằng tiếng Trung. Bạn cần tài khoản Xianyu và một API AI hỗ trợ ảnh nên phát sinh chi phí. README không đưa hướng dẫn riêng cho Windows ngoài Docker. Ngoài ra, kiểu công cụ này phụ thuộc vào cách trang web hoạt động, nên có thể gặp kiểm soát rủi ro.

```note
README nhấn mạnh: hãy tuân thủ điều khoản người dùng và robots.txt của Xianyu, không gửi yêu cầu quá dày, và chỉ dùng cho học tập, nghiên cứu kỹ thuật. Tác giả không chịu trách nhiệm cho thiệt hại khi dùng phần mềm. Bạn cũng nên đổi mật khẩu web mặc định và giữ bí mật file đăng nhập trong `state/` cùng API key trong `.env`.
```

Nếu bạn chỉ thỉnh thoảng mua đồ ở Xianyu, mở app và tự tìm vẫn đơn giản hơn. Nếu bạn thường xuyên săn hàng, muốn có cảnh báo tự động và sẵn sàng bỏ chút công cài đặt, repo này đáng thử. Còn nếu bạn cần theo dõi một sàn khác, đây không phải công cụ dành cho bạn.

## Câu hỏi thường gặp

### ai-goofish-monitor có miễn phí không?

Bản thân repo dùng giấy phép MIT nên miễn phí tải và dùng. Tuy nhiên bạn cần API key của một mô hình AI hỗ trợ ảnh, và nhà cung cấp có thể tính phí theo lượng dùng. README không nêu mức giá cụ thể.

### Có cần GPU không?

README không yêu cầu GPU. Phần phân tích dùng mô hình AI qua API tương thích OpenAI (OPENAI_BASE_URL), nên nặng nhất không nằm ở máy bạn. Tư liệu chưa nêu cấu hình tối thiểu.

### Chạy trên Windows được không?

README khuyến nghị cài bằng Docker, và đây là cách phù hợp nhất nếu bạn dùng Windows. Script start.sh để chạy local là script shell, README không có hướng dẫn riêng cho Windows.

### Cần tài khoản Xianyu không và đăng nhập thế nào?

Có. Bạn cài tiện ích Chrome Xianyu Login State Extractor, xuất trạng thái đăng nhập dạng JSON rồi dán vào mục quản lý tài khoản. File được lưu trong thư mục state/ trên máy chạy dịch vụ.

### Dữ liệu và key của tôi có an toàn không?

Dữ liệu chính lưu trong SQLite tại data/app.sqlite3, còn đăng nhập lưu ở state/, nằm trên máy bạn. Tuy vậy các yêu cầu AI vẫn gửi qua API bạn chọn. Hãy đổi mật khẩu web mặc định admin/admin123 và giữ kín file .env cùng file đăng nhập.

### Dùng công cụ này có bị khoá tài khoản Xianyu không?

README cảnh báo gửi yêu cầu quá thường xuyên có thể làm tài khoản bị hạn chế, và khuyên tuân thủ điều khoản cùng robots.txt của Xianyu. Hệ thống có xoay tài khoản/proxy khi gặp kiểm soát rủi ro, nhưng tư liệu không cam kết an toàn tuyệt đối.

### Có thể dùng mà không cần AI không?

Có một phần. Chế độ 关键词判断 (lọc theo từ khoá) tạo tác vụ trực tiếp mà không qua quy trình sinh tiêu chí bằng AI. Tuy nhiên README liệt kê các biến OPENAI_* là cấu hình tối thiểu, nên bạn nên điền chúng khi cài.
