Skip to content

Frequently Asked Questions

General

What is FenLiu?

FenLiu is a Fediverse content stream filtering system that helps you monitor hashtags, score posts for spam, review content, and export approved posts to Curated Queue.

Why the name "FenLiu"?

FenLiu (分流) means "to divert" in Chinese. It's inspired by the Dujiangyan irrigation system (256 BC), which diverted water using ancient engineering principles. Similarly, FenLiu diverts Fediverse content using modern automation.

Is FenLiu free?

Yes! FenLiu is open-source software. You can self-host it for free.

Installation & Setup

What are the system requirements?

  • Python 3.12+
  • SQLite3 (or PostgreSQL)
  • 100MB+ disk space
  • 2GB+ RAM (recommended)

Can I run FenLiu on Windows?

Yes, but some commands differ:

# Use .venv\Scripts\activate instead of source .venv/bin/activate
# Other commands are the same

How do I upgrade FenLiu?

git pull origin main
pip install -e .
alembic upgrade head

Can I use PostgreSQL instead of SQLite?

Yes! Set the environment variable:

DATABASE_URL=postgresql://user:password@localhost/fenliu

See Configuration for details.

Using FenLiu

How do I add a stream?

  1. Click Streams in navigation
  2. Click Create New Stream
  3. Enter a hashtag (e.g., python)
  4. Select your Fediverse instance
  5. Click Create

What's a good spam score threshold?

  • 0-30: Usually legitimate
  • 30-70: Requires review
  • 70-100: Likely spam

Start reviewing posts with scores above 50 and adjust based on accuracy.

Can I review multiple posts at once?

Currently, reviews are one-by-one. Bulk review operations are planned for a future release.

How do I block a user from being reblogged?

  1. Click Settings
  2. Scroll to "Don't Reblog Users"
  3. Enter the account (e.g., @spammer@bad.instance)
  4. Click Add

Posts from that user will never be exported.

What if a post is blocked but I want to export it anyway?

Remove it from the blocklist in Settings, then the post will be eligible again.

Curated Queue Integration

What is Curated Queue?

Curated Queue is a Mastodon bot that reblogs posts based on a queue. FenLiu provides the queue API.

How do I integrate Curated Queue?

See Curated Queue API Documentation for integration details.

What's the difference between ack, nack, and error?

  • Ack: "I successfully reblogged this post"
  • Nack: "Transient error, try again later"
  • Error: "Permanent failure, don't retry"

What happens if Curated Queue crashes?

Reserved posts timeout after 5 minutes and return to pending. Curated Queue will retry them after restart.

Troubleshooting

I see "database is locked" error

Only one instance of FenLiu can access the database at a time. Stop any other running instances.

Streams don't update

Check that: - The instance URL is correct - You have internet connectivity - The instance is reachable - The hashtag exists on that instance

Image previews aren't showing

  • Check browser console for errors
  • Ensure image URLs are publicly accessible
  • Verify media_attachments is populated in database

API requests return 404

  • Verify the endpoint URL is correct
  • Check the post/resource ID exists
  • Ensure you're using /api/v1 prefix

Queue is stuck pending

  • Check that Curated Queue is running and calling /curated/next
  • Look at Curated Queue logs for errors
  • Verify network connectivity between Curated Queue and FenLiu

Performance & Optimization

How many streams can FenLiu handle?

FenLiu can comfortably handle 50-100 streams with SQLite. For larger deployments, use PostgreSQL.

Should I fetch all streams at once?

You can, but stagger fetches to avoid overwhelming the Fediverse instance. Fetch in batches of 5-10 streams.

How often should I fetch?

Every 5-30 minutes is typical. More frequent fetches may hit rate limits.

Can I delete old posts?

Yes. Delivered posts are automatically cleaned up after 7 days by the background scheduler. You can also trigger cleanup on demand from the Queue Preview page (Cleanup button) or via the API:

curl -X POST -H "X-API-Key: your-api-key" \
  "http://localhost:8000/api/v1/curated/cleanup?retention_days=7"

See Queue Preview for details.

Development & Contributing

Can I self-host FenLiu?

Yes! See Installation Guide.

Can I modify FenLiu for my use case?

Absolutely! FenLiu is open-source. See Contributing Guide.

How do I run tests?

uv run pytest

How do I contribute?

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Submit a pull request

See Contributing Guide for details.

Support

Where can I get help?

How do I report a bug?

Create a Codeberg issue with: - Your FenLiu version - Steps to reproduce - Expected vs actual behavior - Error messages or logs

How do I request a feature?

Use Codeberg Discussions with: - Clear description of the feature - Why you need it - Potential use cases

Still have questions? Create an issue on Codeberg!