From ea7dc75c10bbccf10c909ee602ee5b4a0d6d9ede Mon Sep 17 00:00:00 2001
From: shibao <shibao@bubbletea.dev>
Date: Fri, 6 Mar 2026 02:23:57 +0000
Subject: [PATCH] add readme

---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..471d58d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# Misskey Bulk Export & Backup Tool
+
+This tool is designed to perform a comprehensive, server-side backup of all local users on a Misskey instance. It utilizes both the Misskey Admin API and direct PostgreSQL database access to export data that is typically difficult to retrieve through standard means.
+
+## Features
+
+- **Full User List Export**: Iterates through every local user on the instance.
+- **Notes & Posts**: Exports all notes (public, home, followers, and private), including replies and renotes, to `posts.csv`.
+- **Drive Backup**:
+  - Reconstructs the original folder hierarchy from the user's Drive.
+  - Preserves original file extensions by guessing from MIME types or using API metadata.
+  - Automatically handles filename collisions within the same folder.
+- **Database-Direct Export**:
+  - **User Lists**: Exports all private and public user lists to `lists.csv`.
+  - **Antennas**: Exports all antenna configurations to `antennas.csv`.
+- **Handle Resolution**: Replaces internal Misskey IDs with full `@username@host` handles in all CSV exports (posts, lists, antennas) for better readability.
+- **Profile Data**: Exports user bio, display name, and custom profile fields to `user-data.txt`.
+
+## Prerequisites
+
+- **Python 3.13+**
+- **psycopg2-binary**: For PostgreSQL connection.
+- **Requests**: For API interaction.
+- **Direct Network Access**: The script is configured to talk to the Misskey service via `http://misskey:3000` to bypass Nginx restrictions.
+- **Database Access**: Access to the Misskey PostgreSQL container/service (configured as `misskey-db`).
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Verify the constants in `misskey_export.py`:
+   - `TOKEN`: A Misskey API token with Admin/Moderator permissions.
+   - `INTERNAL_INSTANCE`: The internal address of your Misskey container (default: `http://misskey:3000`).
+   - `DB_HOST`: The hostname of your database container (default: `misskey-db`).
+
+## Usage
+
+Run the script using the system Python:
+
+```bash
+python3 misskey_export.py
+```
+
+The script will create a `backups/` directory in the current working directory, organized by username:
+
+```text
+backups/
+  ├── user1/
+  │   ├── user-data.txt
+  │   ├── posts.csv
+  │   ├── lists.csv
+  │   ├── antennas.csv
+  │   └── files/
+  │       ├── Subfolder_A/
+  │       └── image.png
+  └── user2/
+      └── ...
+```
+
+## Security Note
+
+This script contains sensitive database credentials and an admin API token. Ensure that `misskey_export.py` is stored securely and is not accessible to unauthorized users.